Organize? Software? Documentation? At work?
Don't make me laugh.
Ask HN: How do you organize software documentation at work?
61–70 of 93 posts
Re: Ask HN: How do you organize software documentation at work?
#62I'm pretty new to software docs, having spent most of my career with physical stuff, but my $.02.
A preliminary word about tooling. If you have reviewers and approvers using source control in the day to day, then Docs-As-Code (DaC) is all you need. If you have complex print requirements, or a need for transclusion or conditionals, I'd advocate Asciidoc over Markdown, but if you have a Python-heavy environment ReStructuredText is a heavy hitter once Sphinx is up. This whole paragraph is superseded by reviewer needs - jump down a few paras.
DocToolChain has a fairly well-integrated template for the Arc42 architecture template, with a focus on handling the whole thing Docs-As-Code (DaC) in Asciidoc on generic version control. However, I'm assuming you're talking about user[1]-facing docs, and Arc42 will be of extremely limited use there - although Arc42 could simplify the feeding of your architecture into that of the user facing docs. On that note . .
Is there a general methodology for software documentation? No. That's a DITA trap: thinking that there is a reified "information typing" system that applies to all knowledge. I emphatically disagree with that premise, with every fibre of my being.
Practically, the architecture of your doc setup will depend on a few things. I want to hit on the nuts and bolts without going into domain knowledge. I'm probably failing at that, but that's the intent.
First: your reviewers - what are they most likely to review the docs in? Because review churn is going to be 80% of your time, and doing formal reviews in PDF, while writing in Arbortext, and then making Word track changes out of the PDFs, is one of the more common and more stupid workflows I've had the misfortune to be a part of. Organize it so you're working as close to the review format as possible. Ideally, it's DaC using whatever (.md, .rst, etc), and if you have complex print and component content (CCS) requirements, using Asciidoc. But if your reviewers only touch things in Word, then seriously consider a Sharepoint pipeline. It'll hurt a lot less than using your Special Favorite Tool but having to pipe the edits back and forth for the rest of time. And if they want the Dead Tree Simulator (PDF), well, maybe open up your wallet and go for Framemaker/Adobe Experience Manager. It's going to cost a bundle, but have you ever tried setting up shared PDF reviews on a homebrew CMS with Windows authentication? While also working full time as tech writer? Yeah, it sucks.
To re-iterate: use what the org's using. Whatever efficiency gains come from using Golden Solution X will be completely lost if the rest of the business ignores it.
Second, how do requirements work? Are you just wireframing, pushing it out, then taking the issues that come back in and slapping them in milestones? If that's the case, there's probably not a whole bunch of analysis going on. On the other hand, if someone is really looking at requirements, figuring out which pieces of the codebase can get re-used, all that stuff, you'll be well-served mimicking the architecture your req anal team is working up. Either way, a pretty good architecture is to make some directories in your doc project that broadly cover the bases.
000000_ReservedForPublicationsInternalUse;
001000_LegalSnips
001100_UnicodeDocAttributes
050000_BookMapsThatAssembleDeliverables;
051001_DefaultProductManual
100000_Environment;
200000_Hardware;
300000_Installation;
400000_UserInterfaceDescription;
401000_IndexScreenDescription
401001_Login
500000_GeneralTasks;
501000_AirTravelModule
500101_AirportToAirportSegment
500102_TripBuild
etc.
If the requirements end up sharing a lot of material, consider chunking up the docs so that the parts can be re-used. Asciidoc transclusion and conditionals are in vanilla Asciidoc and they work well. But think very carefully before you go down the re-use road. SERIOUSLY. It's really not worth it unless your content deliverables are duplicating 60-80% of their content, and sometimes not even then, and if it gets borked up you end up with a system THAT MAKES NONSENSE. Please believe what I'm telling you here. You really do have to have the filename thing under control for this to work, and make sure your common repositories (glossary, warnings, legal, etc) are not getting worked by five different people. If you re-use stuff, make the directory structure ONE LEVEL DEEP, so relative paths are the same for both the "chunks" and the "books" that call (include) the chunks. Sure, you can do stuff with `:includedir:`, but it'll be a lot easier to just have a flat directory structure.
[1] "User" as in the sense of "audience consuming docs", not necessarily Joe User.
Re: Ask HN: How do you organize software documentation at work?
#63Who is the audience for your documentation?
If it's nontechnical internal I'd lean towards confluence more. If it's technical external target read-the-docs or the JS equivalent. If you have a venture funded startup, the polish expectation is higher so maybe some type of built website. All of this should run through CI.
Google docs are too loose for my taste to serve as documentation, they are an 80% effort, good for collaboration with non-technical stakeholders, good for live writing but that shouldn't be the end artifact. Slack is also no place for documentation.
--
Here is what I'm targeting for my open source project targeted at technical users
Tutorials are used to walk users through using a project. I frequently use Jupyter notebooks for this and record a video walking through the notebook. The markdown portions are rough talking notes for my narration. The video ends up as a dead artifact, but some people learn better that way. The video is also a lower effort way for people to check out your project. [2] I try not to let perfect be the enemy of good for the videos especially.
I try to incorporate documentation into the development process. Many times I will start documenting a feature and realize it includes too many caveats, then I will redesign the feature so it's easier to document. Often this means that the tutorial comes first and is the only part built.
For API documentation ideally I will have a gallery that renders well, with executable examples that walk through options. Hardcoded small examples are key (avoid faker libraries and excessive scaffolding). React-edit-list has one of the best examples of this I have ever seen [1]
I like to write narrative documentation and sometimes link to the related PRs. The PRs should include the "Why" of the design decisions in their description. Narrative documentation should connect the "what" of API docs. Narrative documentation should also highlight recommended usage patterns.
[1] https://mmomtchev.github.io/react-edit-list/#/simple
[2] https://www.youtube.com/watch?v=GPl6_9n31NE A walk through of how to extend a Jupyter notebook widget I wrote.
Re: Ask HN: How do you organize software documentation at work?
#64Earlier quoted context omitted.
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…
Sure you could re-invent source control, ownership models, bug tracking, change review and merge processes in a wiki. Or you can use the tools that we already have for that. The main point is you need ownership and responsibility. Wikis by design don't have those things, and it shows in how people actually use them. Wiki dumpsters are popular exactly because they let people abdicate responsibility, which means docs a…
[deleted]
Re: Ask HN: How do you organize software documentation at work?
#65Documentation of interfaces between components that are owned by different organizations get my full attention and care.
Everything else is best effort.
Re: Ask HN: How do you organize software documentation at work?
#66Earlier 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 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 system it can only ever attempt to be accurate for whatever the most recent release is. This is bad for people running older versions, and also makes it harder to develop documentation for unreleased code in a way that isn't potentially confusing.
Re: Ask HN: How do you organize software documentation at work?
#67Never 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.
This is my experience as well. I don't say it can't be done, but I've seen this happen multiple times. And with GitHub wikis, in particular, it makes it very hard to have docs tied to specific versions of the software.
Re: Ask HN: How do you organize software documentation at work?
#68Earlier quoted context omitted.
> Five years and 80% employee turnover from now, your git docs will be a completely unsearchable pile of outdated trash from employees who don't work there anymore Throwing your own other comment back at ya :D If docs aren't maintained and curated then it doesn't matter if they are in a wiki, word docs, printed pages in a file cabinet or in the repository as markdown files. Getting team discipline around updating doc…
Yeah of course you can have bad docs in any system. But wikis actively encourage a bad ownership model (i.e. none). You could put in a bunch of work to build up an ownership and change review system around a wiki, I guess, but we already have tools for that. Use those instead!
I agree with you but I also don't see how using source control is a solution to any of it. In my experience, repos go orphan quite regularly in large companies. In the end of the day, documentation requires maintenance.
With that said, there are times where docs in source control are totally viable, especially when their scoped to the repo they are located in.
Re: Ask HN: How do you organize software documentation at work?
#69I'm responsible for a number of Java products. I try to provide high-quality Javadoc for all public library interfaces, library user's guides where appropriate, and development guides for applications. The latter two take the form of MDBook documents (https://rust-lang.github.io/mdBook/), with the document source living in the GitHub repo so that it's tied to the particular software release in a natural way.
Re: Ask HN: How do you organize software documentation at work?
#70Never 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.
Wiki is third-worst. Even worse than wiki is Slack. Even worse than Slack is "ask so-and-so".
If you destroy wikis without an alternative, they'll be replaced with one of the worse options.