Ask HN: What platform/tool do you use for software documentation?
12 comments
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.
* 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.
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.
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)
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").
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
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).
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.
Agreed though, code docs should be in the code. With the code or in well placed READMEs.
Confluence unfortunately, and readme files in code repos
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.
* 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.
Markdown in project folders (VSCode), versioned with Git.
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.
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.
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.
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.