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.
Ask HN: What platform/tool do you use for software documentation?
11–18 of 18 posts
Re: Ask HN: What platform/tool do you use for software documentation?
#12Plain 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.
Re: Ask HN: What platform/tool do you use for software documentation?
#13I 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.
Re: Ask HN: What platform/tool do you use for software documentation?
#14I 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.
Re: Ask HN: What platform/tool do you use for software documentation?
#15Personally, 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 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
Re: Ask HN: What platform/tool do you use for software documentation?
#16Org 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)
Re: Ask HN: What platform/tool do you use for software documentation?
#17Sphinx 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").
Re: Ask HN: What platform/tool do you use for software documentation?
#18I 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.