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

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).

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.

I suppose I should ask:

* Why are you doing this?

Ask your users.

* If you don't have users, why are you bothering?

* Who is going to maintain it after you're gone?

* How about "living off the land"?

* What about document management?

If it's just you, then delivery is probably more important than maintainability. Maybe it's more important to put the knowledge in a queryable data format if "what" is more important than "why". Delivery might look like PDF or HTML docs.

Your users might prefer HTML or (urrrp) Word. Or (gerp) Confluence. You can try to influence that, of course.

If it's code, e.g. Java or Python, there are built-in doc formats.

Finally, how are you going to manage the evolution of that documentation: you need to at least give passing thought to versioning and who can edit.

Swagger and Jupyter Notebook come to mind as creative approaches focused on particular problems. I've used Microsoft Access to document requirements and dependencies.

I wrote HTML with Notepad 20+ years ago in a CMM 3 shop (served off of a file share), and that created a whole committee to decide what a "document" even was.

I've used self-documenting / low code / no code approaches from time to time when crafting operational systems when I expect to immediately lose control to inveterate tinkerers.

Plain markdown files is definitely the way to go. It's easy to create a basic table of contents and arrange them in a tree-like manner. You can view them rendered in a GitHub project.

If you want search and some other features, consider the mdbook project used by Rust. It's not specific to Rust and it's pretty slick.

I have used docusaurus, vuepress, mkdocs, antora, and asciidoctor for documentation. I like mdbook the best.

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.

I wish it received more love, because asciidoc does. It's a complete documentation system allowing the users to write simple docs or full fledged books at ease.

It still remains a mystery to me, why markdown is hyped, and asciidoc seems to be nearly unknown.

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.

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

What was Docusaurus missing?

So the main issue was nesting sections into sections, became really hard to organise the navigation. When it was <50 pages it was great - now >100 it just became unusable. The final blow was needing to bring team members onboard from other disciplines to help, markdown was lost on them

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

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.

Org Mode is great, although writing extensive docstrings so you can just get the variable/function/macro/whatever described from the REPL is also nice.

  (describe 'cons)

Would show you how the cons function works, and information about the cons type, for example.

Sphinx offers a great balance for me, with its ability to have free-form markdown-like (restructured text) files, combined with the ability to bring in documentation from comments/docstrings in the source code (via "autodoc").

Confluence unfortunately, and readme files in code repos

I'm trying to use obsidian to author markdown files in the same repo as the code. Not totally convinced yet but also haven't given up.