Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: How do you organize software documentation at work?

news.ycombinator.com

Post reply on HN
Print view View original

71–80 of 93 posts

Re: Ask HN: How do you organize software documentation at work?

#71

Post by breischl »

coldpie wrote: post #4

Never use a wiki for anything. Wikis are the number one worst form of documentation. They are worse than no documentation. Wikis explicitly destroy the concept of ownership and responsibility, and without those, what you get is a big pile of outdated, unorganized trash that no one maintains. Destroy wikis.

You seem to be thinking specifically about documentation for one particular project, eg API docs. And in that context I'd agree.

But Wikis are useful for things that are shared, or that are not tied to a particular product, or don't exist in the product yet. eg - "What's the temporary workaround for this bug?" - "How do I get started as a new employee?" - "What information do we need on customer requests?" - "What's the team process for handling escalations?" - "Here's the preliminary design for this new feature"

You still need someone to update those docs, but it's nice if, eg, the manager (or product/project manager) who isn't in Git all day can do it easily instead of asking a dev to do it.

Re: Ask HN: How do you organize software documentation at work?

#72

Post by YeahThisIsMe »

We add a new system of doing it every couple of months to years and then don't migrate everything over from the old system, so they all still see changes.

Documents in a file system, Confluence, a Wiki, docs in project repositories and a special documentation repo.

Re: Ask HN: How do you organize software documentation at work?

#73

Post by umamike »

bmitc wrote: post #40
coldpie wrote: post #37

Earlier quoted context omitted.

Five years and 80% employee turnover from now, your wiki will be a completely unsearchable pile of outdated trash from employees who don't work there anymore. Wikis are not documentation, they are dumpsters you can rummage through and try to find a nugget of wisdom. Don't make your new employees rummage through dumpsters.

Just because someone is bad at curating documentation doesn't mean it is inherent to wikis. Wikis and repository-sourced documentation are under the same constraints of requiring curation. There is no "automatic" documentation that happens. It has to be written, updated, maintained, and publicized. People's problems with documentation are they don't want to deal with it. It's usually not about the systems used to doc…

I like to think of it as a garden, you're continually planting and pruning. When things die you remove them. You do your best to figure out where to plant new things.

Re: Ask HN: How do you organize software documentation at work?

#74

Post by bmitc »

frfl wrote: post #50
bmitc wrote: post #42

I generally like using a combination of the following: * Wikis for general information, environment setups that are not project specific, etc. * Repositories to host code and system specific information, usually in Markdown documents. * Google Docs or Microsoft 365 for working documents that need to be collaborated on, commented on, and shared without the rigmarole of pull requests and the more static nature of wikis…

https://app.diagrams.net (formerly known as draw.io) can be exported and imported as an XML. At one company we just exported the diagram as a png/jpg and as an xml, committed both to the wiki repo or source repo under the docs/ directory. Then next time, just import the diagram xml into the app and repeat. I think that's a good enough approach if diagrams are useful but updated infrequently. I've started using a simi…

I definitely have made decent use of Mermaid diagrams in GitHub. But Mermaid diagrams are hard to layout, and there is only one experimental layout that's good for automatically generated diagrams. It's nice, but it's not quite there. I have tended to bounce between Mermaid and Visio.

I'm generally not a fan of exporting and importing diagrams constantly. One thing that is nice is that Confluence can support plugins for diagrams, which is okay-ish.

Re: Ask HN: How do you organize software documentation at work?

#75

Post by frfl »

bmitc wrote: post #74
frfl wrote: post #50

Earlier quoted context omitted.

https://app.diagrams.net (formerly known as draw.io) can be exported and imported as an XML. At one company we just exported the diagram as a png/jpg and as an xml, committed both to the wiki repo or source repo under the docs/ directory. Then next time, just import the diagram xml into the app and repeat. I think that's a good enough approach if diagrams are useful but updated infrequently. I've started using a simi…

I definitely have made decent use of Mermaid diagrams in GitHub. But Mermaid diagrams are hard to layout, and there is only one experimental layout that's good for automatically generated diagrams. It's nice, but it's not quite there. I have tended to bounce between Mermaid and Visio. I'm generally not a fan of exporting and importing diagrams constantly. One thing that is nice is that Confluence can support plugins…

diagram.net also has an electron app. I realize I can just have it open the xml in the git repo directly, no separate tedious import step that way. That was quite nice and a happy accident that I discovered.

Re: Ask HN: How do you organize software documentation at work?

#77

Post by incrudible »

YeahThisIsMe wrote: post #72

We add a new system of doing it every couple of months to years and then don't migrate everything over from the old system, so they all still see changes. Documents in a file system, Confluence, a Wiki, docs in project repositories and a special documentation repo.

That leaves a lot to be desired. May I suggest putting some in Jira, one or more blogs, and a custom QA ticketing system?

Re: Ask HN: How do you organize software documentation at work?

#78

Post by fuzzfactor »

Here's an example of how Microsoft sets an example, just a random discovery from just yesterday.

The REAgentC.EXE command is the configuration agent for the Windows Recovery Environment.

"Complete", "comprehensive", reference documentation is here:

REAgentC command-line options:

https://learn.microsoft.com/en-us/windows-hardware/manufactu...

Where the detailed syntax and command-line switches are each "fully" documented in "expanded" webform by default, but the short "header" alone is "unexpanded" and shows only pointers to the first 3 CLI switches:

>In this article

> REAgentC syntax

> /setreimage

> /enable

> /disable

> Show 5 more

until you click "Show 5 more" and then you get the "entire" list:

> REAgentC syntax

> /setreimage

> /enable

> /disable

> /boottore

> /setosimage

> /info

> /setbootshelllink

> Related topics

> Show less

Helpfully this page is dated from 2022 AUG 18, and there is a table of contents in the left-hand frame linking to other pages from the series, but this is the one page known and designated as "REAgentC command-line options" so you've got to figure that this page is core and at least mentions all the options even if further pages would be necessary to fully explain their implementation.

At the bottom of the page after all the /switches have been documented, for further info there is a link to "Related Topics; Windows RE Troubleshooting Features" which is from 2021 DEC 15. Good information there, but nothing more about the switches.

For that you need to click on "Add an update package to Windows RE" from the table of contents to the left:

https://learn.microsoft.com/en-us/windows-hardware/manufactu...

This how-to article appears earlier in the Recovery Environment documentation series, quite a bit before the command-line options are summarized on the final command-line options "reference" page. However this tutorial page is from 2024 FEB 09, so about as current as can be. This is key.

And that's how we can learn about the underdocumented Reagentc switches that can be used to mount and unmount recovery images on a running PC rather than an "offline" image.

The example mentions "ReAgentC.exe /mountre /path c:\mount", and "ReAgentC.exe /unmountre /path c:\mount /commit".

So at least two more reagentc switches are functional now, but not included in the above reference list:

/mountre

/unmountre

Maybe someday these apparently new features will be documented on the main options page like you would expect from a company that is supposed to value keeping up-to-date.

Re: Ask HN: How do you organize software documentation at work?

#79

Post by globallyunique »

simonw wrote: post #12
softwaredoug wrote: post #2

I hate, hate software documentation as a concept. It gets out of date and is hard to use. It's a last resort, only for specialized cases. I prefer two types of documentation: 1. Executable documentation - tests, asserts, even things like Jupyter notebooks that can be tested and executed 2. Timestamped documentation - documentation that has a clear date on it of when it was valid. So the reader has an expectation "Thi…

I think there's a solution for avoiding zombie documentation. The documentation lives in the same git repository as the code that it documents. Inaccuracies or out-of-date documentation is treated as a severe bug. Issues are filed, the documentation gets fixed. This is crucial, because if zombie documentation is allowed to persist it causes people to lose trust in the documentation, which means they won't refer to it…

I like the idea as an engineer - but this makes it so non-technical people are less likely to write docs. If your marketing manager needs git access and to edit a markdown file on GitHub - the chance they will document in even ideal conditions goes way down

Re: Ask HN: How do you organize software documentation at work?

#80

Post by perrygeo »

For technical docs, I always advocate for documenting in source-controlled markdown. For all the same reasons we source-control our code. It's the bare minimum requirement for quality control of professional software work; no one would take a programmer seriously if they refused to put their code into source control and insisted on pasting code snippets around in a dozens of various tools and live-patching prod! Yet we do this with docs all the time. It's no surprise that we struggle with doc quality since its treated as second class to code.

If you want quality docs, we have obvious tools for that. Treat it like code. If you want to keep pasting random thoughts around and calling it "documentation", don't act surprised about the dismal state of your wikis.

Post reply on HN