Ask HN: What platform/tool do you use for software documentation?

#1

Post by pablolec » Sat, Dec 03, 2022, 10:31 AM UTC

I don't have many years of experience and in a professional context, I always found documentation to be hard to use, hard to navigate, near only usable if you use the search bar and know what keywords to type.

I'm going to inherit the responsibility of a medium-sized legacy system with close to 10 years of undocumented code so I would like to do something about it.

There is a small Confluence but Jira-related stuff is a no-go for me.

I sometimes use Notion, but I find the possibilities are so broad it requires work to make things not messy. But Notion is an option, maybe you know some pre-made templates or good examples I could use?

Further than that, I don't have any other platform in mind. Self-hosted is not what I'm looking for, and neither are tools to build docs. That may look neat but I'm searching for a platform to quickly iterate, where other devs could participate without downloading anything or going through a pipeline.

EDIT: Other than my specific need, I'm curious to know what you use to write docs.

Re: Ask HN: What platform/tool do you use for software documentation?

#2

Post by lionnn » Sat, Dec 03, 2022, 10:57 AM UTC

Personally, Notion, however, previously GitBooks (which got very expensive) then Docusaurus (which eventually we outgrew)

Re: Ask HN: What platform/tool do you use for software documentation?

#3

Post by oxff » Sat, Dec 03, 2022, 11:21 AM UTC

If this is for software developers, Notion also belongs to trash. It is slow to use, you need to click for everything etc.

The best documentation is straight in the code file: module documentation at top, then method documentation for each method with a simple example / doc test showing what is the input-output relationship, the second best is an .md file in same repo etc. the more friction you add the worse you make this process for software developers (Jira / Confluence as the king dog shit of documentation process - these are not for developers these are for people who need job security).

Re: Ask HN: What platform/tool do you use for software documentation?

#4

Post by Dowwie » Sat, Dec 03, 2022, 12:48 PM UTC

lionnn wrote: post #2

Personally, Notion, however, previously GitBooks (which got very expensive) then Docusaurus (which eventually we outgrew)

What was Docusaurus missing?

Re: Ask HN: What platform/tool do you use for software documentation?

#5

Post by geoffbp » Sat, Dec 03, 2022, 1:22 PM UTC

Confluence unfortunately, and readme files in code repos

Re: Ask HN: What platform/tool do you use for software documentation?

#6

Post by t312227 » Sat, Dec 03, 2022, 1:45 PM UTC

idk ...

* md files in a git-repo

and a transformation to html/pdf/whatever

* some wiki

personally i prefer something FOSS like mediawiki and i have to admit, i dislike confluence a lot, but especially larger companies use it all over the place.

Re: Ask HN: What platform/tool do you use for software documentation?

#7

Post by jasfi » Sat, Dec 03, 2022, 1:46 PM UTC

Markdown in project folders (VSCode), versioned with Git.

Re: Ask HN: What platform/tool do you use for software documentation?

#8

Post by type0 » Sat, Dec 03, 2022, 2:52 PM UTC

I have used Antora and think it's awesome, I would have preferred Asciidoctor + a bunch of my own Ruby scripts but that's only because I dislike JS.

Re: Ask HN: What platform/tool do you use for software documentation?

#9

Post by stitched2gethr » Sat, Dec 03, 2022, 3:30 PM UTC

oxff wrote: post #3

If this is for software developers, Notion also belongs to trash. It is slow to use, you need to click for everything etc. The best documentation is straight in the code file: module documentation at top, then method documentation for each method with a simple example / doc test showing what is the input-output relationship, the second best is an .md file in same repo etc. the more friction you add the worse you make…

I use Notion for general docs and it's... fine. It has basically everything I want from a general document manager without getting in the way.

Agreed though, code docs should be in the code. With the code or in well placed READMEs.

Re: Ask HN: What platform/tool do you use for software documentation?

#10

Post by KronisLV » Sat, Dec 03, 2022, 4:38 PM UTC

Other people mentioned code comments and Markdown files, I'm inclined to agree.

I've used code comments pretty well to explain both non-trivial technical details, as give a quick rundown of business requirements that are the basis for some code existing, maybe with links back to an issue tracking system where more context is needed. Markdown files are better if you want to include images/videos/animations/diagrams and provide more context, or step by step instructions on how to do something, which is great because you can easily search through them, as they're just text. Code can typically explain what it does itself but not necessarily why, so it's great to have either of the tools at your disposal.

Of course, there's nothing wrong with external Wikis either, though some are implemented better than others IMHO.

Confluence is sometimes the only choice you get, so having it is better than having nothing.

GitLab and GitHub also have integrated Wikis, as do other solutions: https://docs.gitlab.com/ee/user/project/wiki and https://docs.github.com/en/communities/documenting-your-proj...

For ones to host separately, I've found BookStack to be pretty good in its simplicity/usability/performance: https://www.bookstackapp.com/

As for things that are meant specifically for documentation, Read the Docs might be of appeal to some: https://readthedocs.org/

You can probably also use Sphinx (used by Flask): https://www.sphinx-doc.org/en/master/ or MkDocs: https://www.mkdocs.org/ or something else entirely.