What do you use for public-facing documentation?

News & General Discussion
1

So I’ve come full circle once again and need to vent a litte, and hopefully someone can suggest me a gem I haven’t seen yet.

Eventually I need a public-facing documentation site for my assets. However, the tools I found either suck or they are ridiculously expensive. Some are both.

I used to use and love Confluence. However, they changed their entry-level plan to no longer include public access, so now you have to dole out $55 per month at a minimum. And as far as I remember you cannot (easily) import static websites (ie API references). But okay, those could still be on github.

Per suggestion by Unity I was checking out GitBook, but I was put off by the lack of navigation features. In particular if you have multiple projects, you can at best hide the projects under a single button while losing the versioning feature. At least as far as I understood. Any sort of navigation changes seem to be locked away under the Enterprise plan, so there’s no way to create something like the Netcode docs. But the best thing is: their price goes from free to $7 to $12,50 plus 82,50 one-time fee … no, wait, seriously, they actually mean $12,50+82,50 = $95 per month ($1140 annually)!! There goes the PDF export option and content feedback.

So then, maybe Read the Docs? It’s not as comfortable but hell, it’s free. Right? Nope! They hide this very well but for businesses it costs something. Yeah okay it’s only $5 per month soooo … no … wait … that plan says it enables “public-facing docs” and it’s only $150 per month!!! :hushed:

So then … why not Github pages? Well, it works but … having to wait 30 seconds or more with no indication whether the static page generation process has finished is super super annoying and makes that practically useless if you want to write good docs, with the page preview at best being an estimation of what the published page might look like. If you’re the write&forget type of editor it may be okay but not for me.

Pages may still be the most cost-effective solution if you get to set it up with Jekyll locally and end up publishing it after you’ve made all changes. I’m however not inclined spending a large portion of doc-writing time on technicalities like setup and synching content and there’s probably always some issues where you have to get dirty with config files and the command line.

I was also looking at and quickly dismissing “Hipster” doc sites like Bit.AI and Nuclino and Scribe (different purpose).

So, what else is there that is comparable to GitBook and Confluence for software documentation?

PS: if you’re wondering why I’m not going for a lower-tier plan … I always check the pricing progression because eventually, and often sooner than you’d think, you’re inclined to upgrade. And the lock-in is real, theoretically you can export/import but this never works anywhere near flawlessly.

1 Like
2

Are you generating your documentation as part of your source code?

C# has Quick Start | docfx
It can generate static pages from your /// comments and also .md files

Otherwise I just use Jekyll to manage public pages, but mine are just for public facing pages for games (not assets)

3

I would just run doc pages on rented hosting. Deadly cheap. Just don’t go to godady hosting, it will limit what you can do.

Link references to scripts on the doc. You can even put own git on the hosting. Or wiki. But foremost if you do scripts assets, leave explanations comments in relevant scripts. It is best documentation. Is easier to maintain, than updating doc pages individually.

And also you can auto gen doc files from scripts. There are some tools hovering about in the forum, or on te net, which genrete HTML doc files.

Actually I do wonder, if VS can generate them too?

4

Yes I will but mainly I want to write tutorials and such.

I’ve used DocFX and will use it again but … oh boy, setting that sucker up was a major major headache due to - you wouldn’t believe it - the downright terrible documentation of DocFX.

5

Try GitBook

6

I did. Totally not happy with that. It looks cool on first sight, however the price step from Plus to Pro is going from $8 to $114 per month for very little extra features. But besides that, you can only have 4 (in words: FOUR) fricking header links that hardly work for navigating between different spaces of the documentation because each space has its own unique set of header links to configure. And no way of indicating which of these header links is “active”.

Lastly, the simple fact that you cannot get your documentation exported (except PDF, which is non-editable and requires the hefty Pro version). Once you’re in, you’re locked in. That’s a worst-case no-go dealbreaker!

For an indie developer’s point of view, Gitbook is pretty much a greedy rip-off. I’d much rather shell out $50 per months on Confluence and get way better customization and navigation features.

7

Have you looked into publishing a OneNote Notebook via SharePoint or a different sharing service?
My company uses that for dev notes alongside confluence docs but it feels feasible to write whole docs in OneNote.

8

Nope, haven’t. Might work but only if hyperlinking documents work and there’s a browsable tree of docs.
Hmmm I think if I use Office for commercial purposes I probably have to pay for that though.

9

OneNote is limited to three hierarchy levels:
The notebook, sections and pages.
Not a huge lot, but honestly that forces a nicely shallow overall structure. Any of them can be linked.

Good point, though I would suspect an older pro version of office would suffice? At least no running costs from this.

The possible solutions are surprisingly scarce it seems. No wonder most docs I’ve seen on the web and the asset store are either PDFs or self hosted with some generic CMS made for blogs or news.

10

If you have tried a lot of the off the shelf solutions and have such a specific set of requirements that none of them really work on either features or pricing, the next logical step would be to host these yourself using a personal website.

That way you can have absolute control over everything - its more work initially but once you have some sort of CMS setup you could end up with something thats tailored exactly to what you need

11

Alternatively you can pick one of the many existing managed website providers. Squarespace, for example, is only a little more money than hosting a website yourself and provides ways to import custom HTML and CSS.

https://www.squarespace.com/pricing
https://www.charlotteohara.ca/blog/add-custom-code-squarespace-website

12

It’s not statically generated, but Github has a wiki section for projects that is pretty usable. Otherwise I use a wiki system like mediaWiki or wiki.js and self host it.

13

I think I need to misuse this thread to rant about GitBook. This thing is driving me NUTS!

Just a couple things I noticed while working on it today:

  • Edit a page, make changes, then click on another space => all edits are lost! No warning! :rage:
  • Want to use header links for navigation between spaces? You have to configure these header links manually and individually in every space. :roll_eyes:
  • It keeps telling me to “Type OPTION / for commands …” - first of all, I’m not on a Mac, and secondly, one does not simply type Ctrl / on a non-US keyboard! :rage: (the / character is on Shift+7 and Ctrl pressing the key where / is on US keyboards results in the browser zooming out)
  • I pasted several images one after another from my clipboard into a page. Now I cannot move them apart by using my cursor and pressing Return or something. :eyes:
  • I try the option “convert image to block” and it converts exactly ONE image to a block image, the others I pasted to the same paragraph are simply gone. No undo. :rage:
  • Speaking of images: no matter how tiny, when a user clicks on an image, it goes fullscreen into gallery mode. Furthermore, each gallery popup is only for “1 / 1” images no matter how many images are on the page. :face_with_spiral_eyes:

If it keeps going on like this I cannot be held responsible for what follows … seriously. What an increasingly intolerable UX experience. :frowning:

Yes, I’m spamming them with my remarks but I’m close to giving up … this isn’t making documentation easier, let alone enjoyable.

1 Like