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

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 "This was true at X date, but may not be true now". This includes detailed pull requests and git commit messages.

https://softwaredoug.com/blog/2023/10/13/fight-undead-docume...

I wrote important steps for every task to text file, commands, examples, good code snippets. then it simple to remember already researched information for often similar improvements for project codebase.

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.

Where I work, we use Confluence and Backstage. Confluence sucks and Backstage, although I conceptually consider it appealing, sucks too.

I have yet to see a good documentation strategy. We have quite some awareness about the problem but I don't see an easy exit.

Currently, we have a similar dumpsterfire running. Project / guideline / bla documentation hanging around in Confluence, technical documentation snippets in git repositories "near" the code they belong, some folks scourging themselves with Sharepoint and there's no solution in sight.

Me and some colleagues have developed quite some tendencies against natural language documentation because it basically becomes stale as soon as you publish it into your org.

HTML excels at this. Also has the advantage of not depending on a third party with all the compromises that entails.

5. Google Meet or Zoom call.

Depending on the complexity of the project, short text documents about architecture on Github are OK. Still you have to be careful to document only the most important things that are worth keeping up to date, and then actually doing that.

My workplace uses Confluence.

I hate it for a very simple reason: the code (in BitBucket) and the documentation are disconnected.

I want my code and documentation to be coherent with each other. For small open-source projects (e.g. https://github.com/LaurentRDC/javelin), I love using doctests which ensure some level of coherence between documentation and code.

At a previous employer people constantly complained about the lack of documentation. Once I started digging in I realized we actually had LOADS of documentation, but it was spread across (genuinely) 11 different systems!

I span up a search engine that covered as many of those systems as possible (just SQLite FTS with Datasette, cron tasks that indexed various things and a simple custom search UI) and it helped a lot, because people at least had a fighting chance of finding stuff.

I believe there are off-the-shelf solutions for this kind of thing now, though I don't have experience with any of them myself.

I've since recreated aspects of the search system I built there as https://github.com/dogsheep/beta - you can see a working example of that system on the Datasette site here: https://datasette.io/-/beta?q=geojson

Code comments + Slack. GitHub and Slack search are great if you know how to use them and I have yet to find something I couldn’t answer with these tools.

People like to say “Slack isn’t documentation” but in reality it’s a better documentation than some outdated Wiki nobody is touching.

we use Notion for anything that doesn't fit in one of the code repos, like process docs and platform architecture notes.

Our projects have a certain need for documentation that describes the exact meaning of various data fields in files/APIs/DB entries, etc.

We have decided that the best place for the "single source of truth" for that is right next to the appropriate code in git, with the various build/deployment scripts ensuring that copies (explicitly unmaintained, unmaintainable, read-only) of that get packaged with the actual systems, with the packaged libraries, linked in their web backends, etc. We don't care much about the format of the document, whatever fits the particular needs best - e.g. sometimes it's markdown, sometimes it's Excel.

The key factor here is to ensure that (a) there's a single source of truth; (b) you can have the same atomic commit/pullrequest/whatever altering both the system and the documentation at the same time; (c) every artifact has the appropriate version of the documentation, instead of going to some internal site or document which might have a different, newer version, you know what is supposed to be true for this release which actually is on this particular server.

I've been loving craft, sadly it's another piece of native mac software keeping me from switching.

(Opinions are my own)

I use (and work on) this: https://www.usenix.org/conference/srecon16europe/program/pre...

Basically docs live next to code or in a team-owned folder if there is no code. Code review happens whenever you change docs.

We use Confluence and markdown files in GitHub. I think we are moving a lot of our docs to Backstage [0] soon.

One process that ends up being really valuable for documentation purposes is our "Architecture Review Documents". This is a standard document that team leads fill out before starting work on a new Saga/Epic/Feature/whatever. It includes the scope and business value of a new feature or large block of work, high level technical architecture of implementation, the impact on existing database schemas and service APIs, etc. This document is presented in a meeting with technical leadership in our organization who deep dive on the topic and explore potential pitfalls in the plan.

The document and recording of that meeting live on forever, and this information is very useful when getting acquainted with a certain part of our product/codebase. You are able to read and hear clearly the intention of a certain service or module, and you can identify several relevant points of contact to ask questions to.

[0] https://backstage.io/

arc42 [1], rendered into whatever format you prefer for reading. In our case we write asciidoc (sometimes markdown) and render it to HTML for each of the releases, so that a version of the documentation is delivered with the release. The authors of arc42 also encourage users to set documentation under version control to ensure one can keep the project and its documentation in sync [2].

[1] https://arc42.org/overview [2] https://faq.arc42.org/questions/G-1/

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.

* Slack is for ephemeral information. If it contains documentation, specification, FAQ, debug steps, process explanations, etc., those should be captured and moved to the appropriate documentation location.

The one thing I really struggle with are diagrams. Cloud-based diagram tools like Visio and Lucidchart are great, but they are tough to save in a good location outside of the cloud environment. It requires exported the file and/or a PDF export. Then, these fit rather poorly into source-code control. There is the concept of "diagrams as code", but all of those systems are generally terrible at layout. There really is no good solution, as there are major trade-offs to both.

Everything in Markdown with the code.

Other parts of the company use Confluence, but the docs with the code are what I pour my heart and soul into.

Slack is always a good resource, but I'd hardly call it "documentation".

I forget the terminology, but there's a good "grid" breakdown of documentation types (I think this one: https://documentation.divio.com ) that I've simplified a bit for the internal documentation I'm involved with.

* README, HOWTO, INFO, PROJECT, DESIGN, NOTES, FAQ

When I pull down a `git` repo, I read the `README.md` (of course). I make my own `NOTES.md` (eg: `.gitignore`'d) of what commands, environment variables, useful blog posts, search results, whatever. Rarely do I share or encourage sharing of `NOTES.md` wholesale, but it's helpful to be able to pull out a few snippets or re-orient myself when coming back to that software/project.

Then, other documents get prefixed with "HOWTO-Do-Some-Specific-Thing.md", or "INFO-Some-Particular-Component.md".

"PROJECT-...", and "DESIGN-..." are "dangerous" ones in that they can quickly fall out of date, but they can be very useful while they're being actively managed. I guess personally I've started making sure to include dates or "eras" in the title, eg: "PROJECT-[2024-Feb]-Add-Foo-Support.md" or "DESIGN-[2024-02-14]-...". Stuff that's outlived its usefulness can probably be moved to an `ARCHIVE/...` in case you need it later, but keep it out of the way from confusing newcomers 1-3 years from now.

"FAQ-..." almost never comes into play (hopefully) b/c it should mostly get absorbed into "HOWTO-..." or product improvements, and few products seem to rise to the level of needing FREQUENTLY asked questions. Ideally FAQ's would "go away" with work on the product or other documentation, but I've had some success with it as like sales-oriented (and ideally: sales-managed) FAQ / Canned Customer Response learnings.

Putting it all together you get something like:

  * README.md
  * HOWTO-Backup-to-S3.md
  * HOWTO-Backup-to-BackBlaze.md
  * HOWTO-Manage-Existing-Backups.md
  * HOWTO-Exclude-Frequently-Changing-Files.md
  * INFO-Supported-Backup-Systems.md
  * PROJECT-[2024-Feb]-Backup-9000.md
  * DESIGN-[2024-Jan]-Auto-Backup-Detection-and-Failover.md
  * NOTES.md (private!)
  * FAQ-Residential-Customers.md
  * FAQ-Business-Customers.md
  * FAQ-Backup-Recovery-Issues.md

Generally, they wouldn't all be "git-adjacent", but `README.md` should link to the other sources, `HOWTO-...` and `INFO-...` is generally good for your wiki/confluence/"published" documentation. PROJECT, DESIGN, and FAQ are all best as "loose" shared docs. Multiplayer by default with low barrier to edit/contribute. Sometimes DESIGN could be INFO-Design-..., or DESIGN might even be a DIAGRAM. You'll know it when you see it.

Prefixing the documentation with the TYPE has been super-critical in adoption. It clarifies that it's not "DOCUMENTATION-About-Some-Thing.md", but instead "HOWTO...(you're gonna do something, goal-oriented)", or "INFO...(you're gonna learn something, no specific outcome)".

If you START introducing new prefixes, then you'll hopefully see them propagate (as appropriate), but ideally whatever vocabulary your business/team ends up using is small (~5-10 documentation types) would cover a good 80-90% of your use cases, and they should be brain-dead simple enough that it's clear their categorization is useful.

Location: Separate Documentation repository in a GitLab group project. That way you have history, notes, membership, ownership, and processes (templates, merge permissions, reviewers)! This can also be included as a submodule in your software repo. And can be used to read/edit by devs in their chosen IDE, or R/W on GitLab via html, or can generate static html documentation via pipelines. Oh, and you can build pipelines to generate html outputs for different use cases, and perform checks, run scripts, etc.

Framework: Choose a framework, like Arc42 for general layout as a good starting point. Remember you have company, quality, project, program, product, process, user, internal how-to's, etc. documentation types not just... user-guides and systems-architecture..so this will be dependent on your org/product. Go for MVP and 80-20.

Plan: Write a plan as part of the documentation that details all of these facets and rules so all contributors understand it.

Formats: drawio.svg for complex diagrams, mermaid for simple diagrams or if important to change manage like code, asciidoc for complex documents, markdown for most/simpler docs. Tables in csv or asciidoc. Images in svg, or png. Everything aforementioned renders on GitLab.

Other rules: Automate everything possible to reduce [manual] documentation. Use text/code vs proprietary formats.

You can get more and more complex with the tech writers, dev, ops, systems, all under one roof and coordinating documentation and pipeline scripting.

Buddy, I'm in _EXACTLY_ the same situation (sub GitLab for GitHub though), so if you see any light at the end of the tunnel, I'd LOVE to hear about it.

Horribly. We use Confluence for much of our documentation, but we can't afford the license to give everybody access to the documentation who needs it, so often we'll be copying data out of Confluence and into google docs. There's an export for that in Confluence but it's buggy on larger documents and often it's just faster to do it manually.

Meanwhile over in google docs it's a trash fire. There's no organization, just documents. At least sharing is possible, and the collaboration is clutch, but documents are copied, those copied edited, then not shared with the originals. It just goes on and on.

Then we have an intranet based documentation system called Papyrs. At least it's a wiki, but nobody maintains it, and search is best described as enabling users to rule out what they're looking for rather than find what they are.

Whatever you do, don't do what we did :)

EDIT: mentioned collaborative nature of google docs

[dead]

Organize? Software? Documentation? At work?

Don't make me laugh.