Your company sounds very similar to everything I've ever dealt with. A mixture of public (API docs) and private (google docs, confluence, floating in random slack threads that you'll never find unless you materially participated in it) sources of documentation.
Ask HN: How do you organize software documentation at work?
81–90 of 93 posts
Re: Ask HN: How do you organize software documentation at work?
#82We 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?
I totally forgot about those, you're absolutely right.
Re: Ask HN: How do you organize software documentation at work?
#83Never 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.
There are downsides to wikis, but suggesting to never use them is quite extreme. What do you propose instead? Putting everything into the repository doesn't always make sense. For example, a development setup at a company or group may require a certain setup that depends upon the operating system and IDE/editor an individual developer uses. This type of information is perfect to put on wikis. It is effectively "globa…
In my experience a wiki is useful to improve the bus count (what happens if key people are hit by a bus). To keep it maintained, establish a culture of using a code review checklist (with things like: does the documentation need to be updated? Is it properly tested? Did the tests fail when the code is intentionally broken or incomplete? Can someone who was not part of the design discussion (nor given any verbal explanation) understand this well enough to maintain it?. Enforce that checklist and improve it (in the same wiki) with time. I think it becomes a big net timesaver and improves quality of life.
Then each team has their own wiki page with a list of "things we care about", each of which links to a separate page that was written using a template of headings, to get minimal (and QUICK TO CREATE) documentation. The template includes about a dozen or less things like: where is the source code, who are the key stakeholders, how do you build it, how & where is it deployed, how are backups done & who is responsible for them, what are the key high-level inputs and outputs, and what else is essential that you want to know, if anything. It is OK to put "N/A" as an answer (if that is true), but all sections are to be completed before it is released.
Those things are separate from the code which is why they are not documented inside the code. They can change even when the code does not, and might sometimes be maintained by non-coders. Code doc comments are more about saying why something was done, in the code, the way it was done.
Then have new people start with the wiki. It should include a section on what to tell new people. This is a potential way to learn, and the new person can have their first task be to update portions of it as they work on new things and work with existing team members. Every attempt to change the culture should be included in the wiki (for example: "we have a rule: no new technical debt. How will we preserve that rule going forward and not just forget like we did in the past? It goes in the wiki and we review it periodically and evaluate how we are doing."). Existing team members should subscribe to change emails so they can verify non-trivial changes!
If there is a QA function, they periodically evaluate (maybe just ask the team) how well the team does at maintaining the wiki pages and following the code review checklist, and reports that to management.
If you don't have people who can or are willing to do that, might be good to ask why, and we all start by looking at ourselves.
Re: Ask HN: How do you organize software documentation at work?
#84Earlier quoted context omitted.
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…
> Inaccuracies or out-of-date documentation is treated as a severe bug. Issues are filed, the documentation gets fixed. Why does this work with Git but not with non-Git? Being in Git doesn't seem to relevant to raising documentation bugs as bugs.
The common logic seems to be that if your documentation is close to the code you're more likely to see that documentation exists and needs to be updated? I think it just boils down to "you must make time to update documentation" and make a process for it, rather than acting like "put your code in git" is some kind of panacea.
Re: Ask HN: How do you organize software documentation at work?
#85Earlier quoted context omitted.
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
I think this is a valid concern, and it seems that most code oasis implementations are starting to add web interfaces for editing files in Git. And a WYSIWYG Markdown editor that can post MRs for people who don't have the ability to directly commit and you're pretty much at Confluence territory (when you have a pipeline to build a doc site with search, that is)
Re: Ask HN: How do you organize software documentation at work?
#86So far no mention of Docbook and just one of DITA. Revealing.
Re: Ask HN: How do you organize software documentation at work?
#87Earlier quoted context omitted.
> Inaccuracies or out-of-date documentation is treated as a severe bug. Issues are filed, the documentation gets fixed. Why does this work with Git but not with non-Git? Being in Git doesn't seem to relevant to raising documentation bugs as bugs.
The main reason is that if it's in Git you can enforce this policy through your PR process. There are a bunch of other reasons to keep documentation in git. The most important is that it gives you versioned documentation that matches your releases - if someone is running v2.3 of your software they can browse the documentation for that exact version using that tag on GitHub. If your documentation lives in some other s…
Understood; I'm particularly talking about using bugs rather than making sure things are ready in PRs.
Re: Ask HN: How do you organize software documentation at work?
#88Never 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.
I remember an anecdote by Will Wright where he said that in large teams they were spending 3 hours in meetings for every hour of work. Wikis were one fix.
Wikis do work for very large user bases, say documenting Stardew Valley mechanics. I think for very large teams, say 50, they start to make sense, especially if you're spending more time in meetings updating everyone than doing work.
Re: Ask HN: How do you organize software documentation at work?
#8999% of people on the Internet are lurkers, and only 1% actually contribute anything ever. By defaulting to action, you can quickly end up wielding a disproportionate amount of influence on the resulting culture of your org. So, not a methodology, but an algorithm I often follow:
If I need to do a thing, and I don't know how to do it, I search for the most obvious sequence of words I can thing that is vaguely like my problem in Confluence. I do this maybe 3 to 5 times.
If I find something, I open it in edit mode and start reading through it. The instant I hit upon anything not obvious to me, add whatever obvious thing is missing.
If I don't find anything in there, I create a page in the Diataxis format (usually a HOWTO) and write it myself. I use short sentences, plenty of screenshots, and plenty of code blocks, to make it as copy-and-paste friendly as possible.
I never ask just how basic this thing actually is - most of my most viewed articles in any organization turn out to be the most basic ones. "How to make a network drive in Windows." "How to set up your Git credentials." These are very often much more popular than "How to build a custom VM inmage with QEMU and Ansible." I take my own confusion as an existence proof that this is sufficiently obscure enough to confuse one generally competent but non-expert person, and take faith that most people in my org are not experts in most things.
I trust other people to be able to look at the timestamps and the history of the docs and to figure out whether what they're reading is too outdated to be useful. I pretend, despite evidence to the contrary, that other people will follow roughly the same algorithm as me, and read pages and make updates on the fly as they work. If they don't, well, that's them ceding their cultural power, which they probably don't want anyway (and that is entirely fair).
Re: Ask HN: How do you organize software documentation at work?
#90Earlier quoted context omitted.
So in order to find documentation, you need to know which repo to look in? How do you deal with cross-cutting concerns, docs that span multiple code repositories?
Yeah, you'll have to sit down and answer that question. Where do docs live? Who is responsible for maintaining them? Wikis let you skip all that, throw the docs into the dumpster, and forget about it until some poor soul comes along and asks a question that's 5 years out of date because they found it on the wiki. Wikis are not a solution, they're giving up.
So what do you suggest? Maybe a dedicated technical writing team? But then you might as well just give them responsibility for a wiki, it doesn't have to be a repository.
> some poor soul comes along and asks a question that's 5 years out of date because they found it on the wiki
This happens if there's docs in a git repo as well.