Ask HN: How do you organize software documentation at work? | Hacker News Reader

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

59 pointsjilles89 comments

Hi folks,

Recently I have ventured into technical writing. At the company I work for, documentation is scattered around ~4 different tools.

1. Google Docs 2. Confluence 3. GitHub (READMEs) 4. Slack

Each of those serves a purpose of course, Google Docs are very collaborative, Confluence is our source of truth, GitHub is mostly for engineering and finally Slack usually has some threads you can find if you run into certain issues.

I am not suggesting we should put all of this into a single tool, but I am wondering if there is a methodology for organizing documentation. I am aware of Diataxis, and want us to use this for certain services / products. What I am looking for in this ASK HN post though, is an overarching methodology of organizing all documentation.

View on HN

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 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 and they won't contribute to it.

Once the documentation is in a trustworthy state, keeping it that way gets a LOT easier. It becomes part of the code review process - a PR won't be accepted unless it updates the relevant documentation that accompanies the code change.

I've been using this policy for my own projects for quite a few years now, and the result is that I'm proud of the state of my documentation for almost the first time in my entire career.

Seems like a great problem for LLMs to help solve as well :)

We should...talk.

For simpler code, can't the solution be a human-enhanced LLM output?

1) LLM scans code updates and approximates output 2) Developer reviews and updates if needed 3) Feed back tagged code and updated output to LLM 4) ? 5) Profit

I tried to get this going on an open source project I worked with, and found basically no support from the other contributors.

I think it basically came down to incentives. Those who were developing the code every day had all the relevant details in their heads. So ensuring that docs matched the code was basically a distraction from their primary goals.

It makes me a little angry because it screws over users of the software. The docs don't even mention that they might be out of date.

> 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.

Understood; I'm particularly talking about using bugs rather than making sure things are ready in PRs.

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.

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)

> I hate, hate software documentation as a concept. It gets out of date and is hard to use.

My response is almost "too bad". :) Keeping things documented is part of the work, and if it isn't done, then the work is not completed.

Your suggestions of (1) and (2) are great suggestions to have as components to the documentation system. Notebooks are really fantastic for this.

> Keeping things documented is part of the work, and if it isn't done, then the work is not completed.

Absolutely. Part of reviewing is checking that the eg. README is up to date and works as expected.

99% 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).

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.

So what do you use instead?

A wiki

Assign domains of the app to developers, the people doing the code reviews require people to update documentation.

Bakes into your existing workflows, direct line of accountability to both the code reviewer and the dev.

The editing software can be anything really.

And ... this can then still be a wiki, right? Not saying that they are the best form, but I think you can combine wikis with people who (have to) take responsibility for certain articles.

I am not OP but I push very hard for docs as code. Your pull request should change content in the ‘src’ folder *and* the ‘docs’ folder.

Especially if making changes to the over all architecture or introducing a new dependency! The team shouldn’t let the PR ,edge until the docs are sufficient

The same tool you use for merging code, with the same ownership & maintainer model. In our case, that's git, and our docs live in markdown files in a docs/ folder.

This doesn't work for documentation that needs to be viewed by people without source-code control access.

Sure it does. As part of your CI process, build your markdown into HTML or whatever and host it.

Slack message received: "Hey, I was reading the documentation and walking through the process and encountered this <bug> and this <typo>. Can you fix <this> and re-export the documentation? Thanks!"

I mean, yeah! That's ideal! If someone doesn't have write access to a repo, then they shouldn't be able to edit the docs for the stuff the repo contains without review either. Just like if they found a bug in the code, they should open a ticket for the problem and the dev responsible for those docs will go fix it.

For us, documentation lives in Markdown in Rustdoc comments above the things they document.

There may be longer write-ups, examples, etc. at the module level.

Documentation gets compiled into a docs.rs-style searchable website like so:

https://docs.rs/tokio/1.36.0/tokio/

Examples are compiled and run as part of the default CI toolchain.

So when a piece of documentation refers to some code that was moved or renamed, it is a bug to not update references in Rustdoc comments.

Comments can still get stale because some programmers write but don't read.

But they're right there on your screen next to the code you're updating.

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.

Fossil SCM, which comes up on HN every once in a while, rolls a wiki and issue tracker in the same repository as source code.

https://fossil-scm.org

> 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 docs is the solution, the place where they are stored is sort of trivial if that discipline exists (fwiw, I've yet to see that discipline).

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.

The arch wiki for example is not perfect, but still helpful to me (and Wikipedia in general). I would not overgeneralize.

So stop using Confluence?

I think that is a better idea than demanding everyone ditching all wikis.

Dokuwiki for example has a sane, plain text format. It can be extended relatively easily compared to Confluence (I have tried both).

Unlike certain other wikis it has access control and unlike Confluence you can edit a single paragraph or section at a time.

And finally, it is actually a wiki, wiki originally meant "quick" I think and I think calling Confluence a wiki in that context is somewhat ironic.

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 "global" information, whereas repositories contain local information. Putting information like this into a repo can increase the barrier to keeping the documentation updated and also requires source-code control access to view, which not everyone has or should have to view documentation.

In my opinion, a combination of wiki documentation plus documentation within the repository are very good. In addition to that, I often use Google's office suite or Microsoft 365 for working documents, that is documents that need to just be written, get collaborative feedback, shared between external and internal people, etc. Then, once they start to solidify and start to get more atomic updates, it makes sense to move them to the wiki or a Markdown document in a repository.

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 document things.

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 are no one's responsibility, because no one likes writing docs.

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.

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.

I will counterpoint slightly to this... I'm currently trying to set up a wiki for my house documentation (eg: TechStack, QuarterlyMaintenance, ValuableAssets, BackupRestore, HomeAutomation, etc...).

When there's a very limited set of curators, a specific topic, and a self-incentive to keep things "up-to-date" wiki's can be a great choice... mostly as like a knowledge base or internal glossary/dictionary.

For true "documentation" (if you don't take the wiki as a whole), and in the corporate world, I agree with the issues against using wiki's.

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.

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.

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.

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.

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

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?

I totally forgot about those, you're absolutely right.

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.

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/

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.

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.

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 similar approach, minus the png/jpg, for my personal markdown based wiki.git, saving the xml as a file that I can reimport in the future. I usually do this for prototyping or grokking some new system.

edit: just remembed, github also supports mermaid diagrams, https://docs.github.com/en/get-started/writing-on-github/wor...

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.

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.

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.

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.

A Slack channel where an issue was discussed publicly, with both the debugging process and the final solution, is priceless. But it only happens with people who also think that.

My experience has been that most info is lost in DMs and video calls. When I helped coworkers, I had to be the one posting the info on public channels if I didn't want to be solving the same problem next week, next month, and half a year later.

Slack is all fun and games until someone pins a password in some channel and now your security team is demanding that all slack messages are deleted after 30 days.

Organize? Software? Documentation? At work?

Don't make me laugh.

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.

I'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.

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.

(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.

Who 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.

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

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.

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/

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.

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.

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".

Documentation sucks. Try Swimm.io - keeps your docs connected to your code (so it automatically update as code change) and also lives in the ide

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

Documentation of interfaces between components that are owned by different organizations get my full attention and care.

Everything else is best effort.

So far no mention of Docbook and just one of DITA. Revealing.

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

Honestly github isn't that bad as a wiki. You get versioning, rich markdown, collaboration, commenting, and it can just be markdown, not some proprietary syntax. And editing right in your browser for non-technical folk, get tell them committing = saving. Might have to manually upload images though. But I recall github supports mermaid diagrams [1].

[1]: https://docs.github.com/en/get-started/writing-on-github/wor...

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

5. Google Meet or Zoom call.

I'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.

Figure out a useful filename convention and police it with githooks / actions. No one commits "newfile01.adoc" to the root directory. ANGRY BUZZER SOUND. Actually, while you're at it, you can hook up pre-commit vs a bunch of automated QA: grammar, cspell, link checkers, all that stuff.

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.

organize? We have a 3 year old outdated confluence page

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.

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.

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

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.

Reply on news.ycombinator.com