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&#x27;s a last resort, only for specialized cases.<p>I prefer two types of documentation:<p>1. Executable documentation - tests, asserts, even things like Jupyter notebooks that can be tested and executed<p>2. Timestamped documentation - documentation that has a clear date on it of when it was valid. So the reader has an expectation &quot;This was true at X date, but may not be true now&quot;. This includes detailed pull requests and git commit messages.<p><a href="https:&#x2F;&#x2F;softwaredoug.com&#x2F;blog&#x2F;2023&#x2F;10&#x2F;13&#x2F;fight-undead-documentation" rel="nofollow">https:&#x2F;&#x2F;softwaredoug.com&#x2F;blog&#x2F;2023&#x2F;10&#x2F;13&#x2F;fight-undead-docume...</a>

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:<p>If I need to do a thing, and I don&#x27;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.<p>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.<p>If I don&#x27;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.<p>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. &quot;How to make a network drive in Windows.&quot; &quot;How to set up your Git credentials.&quot; These are very often much more popular than &quot;How to build a custom VM inmage with QEMU and Ansible.&quot; 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.<p>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&#x27;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&#x27;t, well, that&#x27;s them ceding their cultural power, which they probably don&#x27;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.

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!<p>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.<p>I believe there are off-the-shelf solutions for this kind of thing now, though I don&#x27;t have experience with any of them myself.<p>I&#x27;ve since recreated aspects of the search system I built there as <a href="https:&#x2F;&#x2F;github.com&#x2F;dogsheep&#x2F;beta">https:&#x2F;&#x2F;github.com&#x2F;dogsheep&#x2F;beta</a> - you can see a working example of that system on the Datasette site here: <a href="https:&#x2F;&#x2F;datasette.io&#x2F;-&#x2F;beta?q=geojson" rel="nofollow">https:&#x2F;&#x2F;datasette.io&#x2F;-&#x2F;beta?q=geojson</a>

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

Our projects have a certain need for documentation that describes the exact <i>meaning</i> of various data fields in files&#x2F;APIs&#x2F;DB entries, etc.<p>We have decided that the best place for the &quot;single source of truth&quot; for that is right next to the appropriate code in git, with the various build&#x2F;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&#x27;t care much about the format of the document, whatever fits the particular needs best - e.g. sometimes it&#x27;s markdown, sometimes it&#x27;s Excel.<p>The key factor here is to ensure that (a) there&#x27;s a single source of truth; (b) you can have the same atomic commit&#x2F;pullrequest&#x2F;whatever altering both the system and the documentation at the same time; (c) every artifact has the <i>appropriate</i> 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 <i>this</i> 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.<p>One process that ends up being really valuable for documentation purposes is our &quot;Architecture Review Documents&quot;. This is a standard document that team leads fill out before starting work on a new Saga&#x2F;Epic&#x2F;Feature&#x2F;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.<p>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&#x2F;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.<p>[0] <a href="https:&#x2F;&#x2F;backstage.io&#x2F;" rel="nofollow">https:&#x2F;&#x2F;backstage.io&#x2F;</a>

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&#x2F;edit by devs in their chosen IDE, or R&#x2F;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.<p>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&#x27;s, etc. documentation types not just... user-guides and systems-architecture..so this will be dependent on your org&#x2F;product. Go for MVP and 80-20.<p>Plan: Write a plan as part of the documentation that details all of these facets and rules so all contributors understand it.<p>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&#x2F;simpler docs. Tables in csv or asciidoc. Images in svg, or png. Everything aforementioned renders on GitLab.<p>Other rules: Automate everything possible to reduce [manual] documentation. Use text&#x2F;code vs proprietary formats.<p>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:<p>* Wikis for general information, environment setups that are not project specific, etc.<p>* Repositories to host code and system specific information, usually in Markdown documents.<p>* 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.<p>* 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.<p>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&#x2F;or a PDF export. Then, these fit rather poorly into source-code control. There is the concept of &quot;diagrams as code&quot;, but all of those systems are generally terrible at layout. There really is no good solution, as there are major trade-offs to both.

For technical docs, I always advocate for documenting in source-controlled markdown. For all the same reasons we source-control our code. It&#x27;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&#x27;s no surprise that we struggle with doc quality since its treated as second class to code.<p>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 &quot;documentation&quot;, don&#x27;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.<p>People like to say “Slack isn’t documentation” but in reality it’s a better documentation than some outdated Wiki nobody is touching.

Organize? Software? Documentation? At work?<p>Don&#x27;t make me laugh.

I have yet to see a good documentation strategy. We have quite some awareness about the problem but I don&#x27;t see an easy exit.<p>Currently, we have a similar dumpsterfire running. Project &#x2F; guideline &#x2F; bla documentation hanging around in Confluence, technical documentation snippets in git repositories &quot;near&quot; the code they belong, some folks scourging themselves with Sharepoint and there&#x27;s no solution in sight.<p>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&#x27;m responsible for a number of Java products. I try to provide high-quality Javadoc for all public library interfaces, library user&#x27;s guides where appropriate, and development guides for applications. The latter two take the form of MDBook documents (<a href="https:&#x2F;&#x2F;rust-lang.github.io&#x2F;mdBook&#x2F;" rel="nofollow">https:&#x2F;&#x2F;rust-lang.github.io&#x2F;mdBook&#x2F;</a>), with the document source living in the GitHub repo so that it&#x27;s tied to the particular software release in a natural way.

My workplace uses Confluence.<p>I hate it for a very simple reason: the code (in BitBucket) and the documentation are disconnected.<p>I want my code and documentation to be coherent with each other. For small open-source projects (e.g. <a href="https:&#x2F;&#x2F;github.com&#x2F;LaurentRDC&#x2F;javelin">https:&#x2F;&#x2F;github.com&#x2F;LaurentRDC&#x2F;javelin</a>), I love using doctests which ensure some level of coherence between documentation and code.

(Opinions are my own)<p>I use (and work on) this: <a href="https:&#x2F;&#x2F;www.usenix.org&#x2F;conference&#x2F;srecon16europe&#x2F;program&#x2F;presentation&#x2F;macnamara" rel="nofollow">https:&#x2F;&#x2F;www.usenix.org&#x2F;conference&#x2F;srecon16europe&#x2F;program&#x2F;pre...</a><p>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?<p>If it&#x27;s nontechnical internal I&#x27;d lean towards confluence more. If it&#x27;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.<p>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&#x27;t be the end artifact. Slack is also no place for documentation.<p>--<p>Here is what I&#x27;m targeting for my open source project targeted at technical users<p>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.<p>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&#x27;s easier to document. Often this means that the tutorial comes first and is the only part built.<p>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]<p>I like to write narrative documentation and sometimes link to the related PRs. The PRs should include the &quot;Why&quot; of the design decisions in their description. Narrative documentation should connect the &quot;what&quot; of API docs. Narrative documentation should also highlight recommended usage patterns.<p>[1] <a href="https:&#x2F;&#x2F;mmomtchev.github.io&#x2F;react-edit-list&#x2F;#&#x2F;simple" rel="nofollow">https:&#x2F;&#x2F;mmomtchev.github.io&#x2F;react-edit-list&#x2F;#&#x2F;simple</a><p>[2] <a href="https:&#x2F;&#x2F;www.youtube.com&#x2F;watch?v=GPl6_9n31NE" rel="nofollow">https:&#x2F;&#x2F;www.youtube.com&#x2F;watch?v=GPl6_9n31NE</a> 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&#x27;ve ever dealt with. A mixture of public (API docs) and private (google docs, confluence, floating in random slack threads that you&#x27;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].<p>[1] <a href="https:&#x2F;&#x2F;arc42.org&#x2F;overview" rel="nofollow">https:&#x2F;&#x2F;arc42.org&#x2F;overview</a> [2] <a href="https:&#x2F;&#x2F;faq.arc42.org&#x2F;questions&#x2F;G-1&#x2F;" rel="nofollow">https:&#x2F;&#x2F;faq.arc42.org&#x2F;questions&#x2F;G-1&#x2F;</a>

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.<p>Other parts of the company use Confluence, but the docs with the code are what I pour my heart and soul into.<p>Slack is always a good resource, but I&#x27;d hardly call it &quot;documentation&quot;.

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.<p>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&#x27;t afford the license to give everybody access to the documentation who needs it, so often we&#x27;ll be copying data out of Confluence and into google docs. There&#x27;s an export for that in Confluence but it&#x27;s buggy on larger documents and often it&#x27;s just faster to do it manually.<p>Meanwhile over in google docs it&#x27;s a trash fire. There&#x27;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.<p>Then we have an intranet based documentation system called Papyrs. At least it&#x27;s a wiki, but nobody maintains it, and search is best described as enabling users to rule out what they&#x27;re looking for rather than find what they are.<p>Whatever you do, don&#x27;t do what we did :)<p>EDIT: mentioned collaborative nature of google docs

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

5. Google Meet or Zoom call.

I&#x27;m pretty new to software docs, having spent most of my career with physical stuff, but my $.02.<p>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&#x27;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.<p>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&#x27;m assuming you&#x27;re talking about user[1]-facing docs, and Arc42 will be of <i>extremely</i> limited use there - although Arc42 could simplify the feeding of your architecture into that of the user facing docs. On that note . .<p>Is there a general methodology for software documentation? No. That&#x27;s a DITA trap: thinking that there is a reified &quot;information typing&quot; system that applies to all knowledge. I emphatically disagree with that premise, with every fibre of my being.<p>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&#x27;m probably failing at that, but that&#x27;s the intent.<p>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&#x27;ve had the misfortune to be a part of. Organize it so you&#x27;re working as close to the review format as possible. Ideally, it&#x27;s DaC using whatever (<i>.md, </i>.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&#x27;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&#x2F;Adobe Experience Manager. It&#x27;s going to cost a bundle, but have you ever tried setting up shared PDF reviews on a homebrew CMS with Windows authentication? While <i>also</i> working full time as tech writer? Yeah, <i>it sucks</i>.<p>To re-iterate: use what the org&#x27;s using. Whatever efficiency gains come from using Golden Solution X will be completely lost if the rest of the business ignores it.<p>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&#x27;s the case, there&#x27;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&#x27;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.<p><pre><code> 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. </code></pre> Figure out a useful filename convention and police it with githooks &#x2F; actions. No one commits &quot;newfile01.adoc&quot; to the root directory. ANGRY BUZZER SOUND. Actually, while you&#x27;re at it, you can hook up pre-commit vs a bunch of automated QA: grammar, cspell, link checkers, all that stuff.<p>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 <i>think very carefully</i> before you go down the re-use road. SERIOUSLY. It&#x27;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&#x27;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 &quot;chunks&quot; and the &quot;books&quot; that call (include) the chunks. Sure, you can do stuff with `:includedir:`, but it&#x27;ll be a lot easier to just have a flat directory structure.<p>[1] &quot;User&quot; as in the sense of &quot;audience consuming docs&quot;, not necessarily Joe User.

organize? We have a 3 year old outdated confluence page

Here&#x27;s an example of how Microsoft sets an example, just a random discovery from just yesterday.<p>The REAgentC.EXE command is the configuration agent for the Windows Recovery Environment.<p>&quot;Complete&quot;, &quot;comprehensive&quot;, reference documentation is here:<p>REAgentC command-line options:<p><a href="https:&#x2F;&#x2F;learn.microsoft.com&#x2F;en-us&#x2F;windows-hardware&#x2F;manufacture&#x2F;desktop&#x2F;reagentc-command-line-options?view=windows-11" rel="nofollow">https:&#x2F;&#x2F;learn.microsoft.com&#x2F;en-us&#x2F;windows-hardware&#x2F;manufactu...</a><p>Where the detailed syntax and command-line switches are each &quot;fully&quot; documented in &quot;expanded&quot; webform by default, but the short &quot;header&quot; alone is &quot;unexpanded&quot; and shows only pointers to the first 3 CLI switches:<p>&gt;In this article<p>&gt; REAgentC syntax<p>&gt; &#x2F;setreimage<p>&gt; &#x2F;enable<p>&gt; &#x2F;disable<p>&gt; Show 5 more<p>until you click &quot;Show 5 more&quot; and then you get the &quot;entire&quot; list:<p>&gt; REAgentC syntax<p>&gt; &#x2F;setreimage<p>&gt; &#x2F;enable<p>&gt; &#x2F;disable<p>&gt; &#x2F;boottore<p>&gt; &#x2F;setosimage<p>&gt; &#x2F;info<p>&gt; &#x2F;setbootshelllink<p>&gt; Related topics<p>&gt; Show less<p>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 &quot;REAgentC command-line options&quot; so you&#x27;ve got to figure that this page is core and at least <i>mentions</i> all the options even if further pages would be necessary to fully explain their implementation.<p>At the bottom of the page after all the &#x2F;switches have been documented, for further info there is a link to &quot;Related Topics; Windows RE Troubleshooting Features&quot; which is from 2021 DEC 15. Good information there, but nothing more about the switches.<p>For that you need to click on &quot;Add an update package to Windows RE&quot; from the table of contents to the left:<p><a href="https:&#x2F;&#x2F;learn.microsoft.com&#x2F;en-us&#x2F;windows-hardware&#x2F;manufacture&#x2F;desktop&#x2F;add-update-to-winre?view=windows-11" rel="nofollow">https:&#x2F;&#x2F;learn.microsoft.com&#x2F;en-us&#x2F;windows-hardware&#x2F;manufactu...</a><p>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 &quot;reference&quot; page. However this <i>tutorial</i> page is from 2024 FEB 09, so about as current as can be. This is key.<p>And that&#x27;s how we can learn about the <i>underdocumented</i> Reagentc switches that can be used to mount and unmount recovery images <i>on a running PC</i> rather than an &quot;offline&quot; image.<p>The example mentions &quot;ReAgentC.exe &#x2F;mountre &#x2F;path c:\mount&quot;, and &quot;ReAgentC.exe &#x2F;unmountre &#x2F;path c:\mount &#x2F;commit&quot;.<p>So <i>at least</i> two more reagentc switches are functional now, but not included in the above reference list:<p>&#x2F;mountre<p>&#x2F;unmountre<p>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&#x27;m in _EXACTLY_ the same situation (sub GitLab for GitHub though), so if you see any light at the end of the tunnel, I&#x27;d LOVE to hear about it.

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

I forget the terminology, but there&#x27;s a good &quot;grid&quot; breakdown of documentation types (I think this one: <a href="https:&#x2F;&#x2F;documentation.divio.com" rel="nofollow">https:&#x2F;&#x2F;documentation.divio.com</a> ) that I&#x27;ve simplified a bit for the internal documentation I&#x27;m involved with.<p>* README, HOWTO, INFO, PROJECT, DESIGN, NOTES, FAQ<p>When I pull down a `git` repo, I read the `README.md` (of course). I make my own `NOTES.md` (eg: `.gitignore`&#x27;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&#x27;s helpful to be able to pull out a few snippets or re-orient myself when coming back to that software&#x2F;project.<p>Then, other documents get prefixed with &quot;HOWTO-Do-Some-Specific-Thing.md&quot;, or &quot;INFO-Some-Particular-Component.md&quot;.<p>&quot;PROJECT-...&quot;, and &quot;DESIGN-...&quot; are &quot;dangerous&quot; ones in that they can quickly fall out of date, but they can be very useful while they&#x27;re being actively managed. I guess personally I&#x27;ve started making sure to include dates or &quot;eras&quot; in the title, eg: &quot;PROJECT-[2024-Feb]-Add-Foo-Support.md&quot; or &quot;DESIGN-[2024-02-14]-...&quot;. Stuff that&#x27;s outlived its usefulness can probably be moved to an `ARCHIVE&#x2F;...` in case you need it later, but keep it out of the way from confusing newcomers 1-3 years from now.<p>&quot;FAQ-...&quot; almost never comes into play (hopefully) b&#x2F;c it should mostly get absorbed into &quot;HOWTO-...&quot; or product improvements, and few products seem to rise to the level of needing FREQUENTLY asked questions. Ideally FAQ&#x27;s would &quot;go away&quot; with work on the product or other documentation, but I&#x27;ve had some success with it as like sales-oriented (and ideally: sales-managed) FAQ &#x2F; Canned Customer Response learnings.<p>Putting it all together you get something like:<p><pre><code> * 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 </code></pre> Generally, they wouldn&#x27;t all be &quot;git-adjacent&quot;, but `README.md` should link to the other sources, `HOWTO-...` and `INFO-...` is generally good for your wiki&#x2F;confluence&#x2F;&quot;published&quot; documentation. PROJECT, DESIGN, and FAQ are all best as &quot;loose&quot; shared docs. Multiplayer by default with low barrier to edit&#x2F;contribute. Sometimes DESIGN could be INFO-Design-..., or DESIGN might even be a DIAGRAM. You&#x27;ll know it when you see it.<p>Prefixing the documentation with the TYPE has been super-critical in adoption. It clarifies that it&#x27;s not &quot;DOCUMENTATION-About-Some-Thing.md&quot;, but instead &quot;HOWTO...(you&#x27;re gonna do something, goal-oriented)&quot;, or &quot;INFO...(you&#x27;re gonna learn something, no specific outcome)&quot;.<p>If you START introducing new prefixes, then you&#x27;ll hopefully see them propagate (as appropriate), but ideally whatever vocabulary your business&#x2F;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&#x27;s clear their categorization is useful.