qlyoung's wiki
Page Tools
User Tools

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
documentation [2024/08/28 23:52] – add lots more qlyoungdocumentation [2026/02/12 17:05] (current) – [Tools] promote heading one level qlyoung
Line 1: Line 1:
-I strongly appreciate excellent technical documentation. You can have a great piece of software but if it's difficult to understand how to use it, users will fail to appreciate it.+====== documentation ====== 
 + 
 +I strongly appreciate excellent technical documentation. You can have a great piece of software but if it's difficult to understand how to use it, at best users will fail to appreciate it and at worst huge amounts of time will be wasted and vast quantities of errors committed.
  
 Because I appreciate good documentation for tools I use I do my best to write useful documentation. In addition to the obvious benefit, which is that good documentation saves everyone time, I find there are several additional benefits specific to the act of writing documentation: Because I appreciate good documentation for tools I use I do my best to write useful documentation. In addition to the obvious benefit, which is that good documentation saves everyone time, I find there are several additional benefits specific to the act of writing documentation:
Line 28: Line 30:
 Now, yes, there are the users who show up, ask questions, are referred to the documentation and become combative, refuse to read it, are insulting, etc. Documentation helps us in dealing with these users as well. If the information is well documented, you don't have to interact with them at all! Just refer them to the documentation and move on. You get to completely avoid interacting with toxic people. Now, yes, there are the users who show up, ask questions, are referred to the documentation and become combative, refuse to read it, are insulting, etc. Documentation helps us in dealing with these users as well. If the information is well documented, you don't have to interact with them at all! Just refer them to the documentation and move on. You get to completely avoid interacting with toxic people.
  
-==== arguments against writing docs ==== +===== 'code is law' =====
- +
-=== 'code is law' ===+
  
 You probably know, or you may yourself be, a person who takes an attitude along the lines of "docs suck, code is law. [[just]] read the code lol." You probably know, or you may yourself be, a person who takes an attitude along the lines of "docs suck, code is law. [[just]] read the code lol."
Line 48: Line 48:
   - If you want to write code - I feel for you. Don't you want people to use that code?   - If you want to write code - I feel for you. Don't you want people to use that code?
  
-The last point brings up an important point - if you have zero interest or responsibility for anyone else to use what you're writing, by all means, do not write docs if you don't want to. I am not saying that you need to document everything you make. But for things you intend other people to use, writing docs will make them love you. If you do it professionally, my opinion is that competency in technical writing is part of being a well rounded and competent engineer.+The last point is important - if you have zero interest or responsibility for anyone else to use what you're writing, by all means, do not write docs if you don't want to. I am not saying that you need to document everything you make. But for things you intend other people to use, writing docs will make them love you. If you do it professionally, I will double down and claim that competency in technical writing is part of being a well rounded and competent engineer.
  
-=== docs go out of date ===+===== culture =====
  
-Yes they do. But if this is a significant burden, you are probably doing one of these things wrong:+In a professional context, company culture frequently does not incentivize documentation. Technical output is rewarded. Documentation output is not. This is extremely common, but it is bad for the organization as a whole. Suppose you commit an engineer to building out a complex system, but there are no cultural incentives for the engineer to write good documentation, so they don't. How many man hours are subsequently wasted by users who are forced to reverse engineer that system in order to use it? Probably a lot, right? Imagine if the engineer was rewarded for writing good documentation and did so. Yes, the engineer spent time writing documentation when they could have been doing technical work. But how many hours are now saved for other users?
  
- +Of course, some teams are explicitly aware of that tradeoff. Externalizing cost to other teams means your team can be more productive - at the cost of the org. Dsyfunctional workplaces incentivize this behavior.
-=== culture === +
- +
-In a professional context, one reason docs frequently do not get written is culture. Technical output is rewarded. Documentation output is not. This is extremely common, but it is bad for the organization as a whole. Suppose you commit an engineer to building out a complex system, but there are no cultural incentives for the engineer to write good documentation, so they don't. How many man hours are subsequently wasted users trying to reverse engineer the product in order to perform basic tasks? Probably a lot, right? Imagine if the engineer was rewarded for writing good documentation and did so. How many hours are now saved?+
  
 In extreme cases, this can result in the entire product being rebuilt by a different person or team because no one can understand how to use the first product. In extreme cases, this can result in the entire product being rebuilt by a different person or team because no one can understand how to use the first product.
  
-At work we have an internal service that has an HTTP API. Said API requires authentication. Yet, nobody has bothered to write down how you actually authenticate to this service. It's extremely simple, so simple you can explain it with just two lines of example shell code. But somehow nobody has taken the 2 minutes to locate an appropriate place to write that down, jot it down and provide a couple notes on it.+There is a service I interact with that has an HTTP API. Said API requires authentication. This service is maintained by a team. Yet, nobody has bothered to write down how to authenticate to this service. It's extremely simple, so simple you can explain it with just two lines of example shell code. But nobody has taken the 2 minutes to locate an appropriate place to write that down, jot it down and provide a couple notes on it.
  
 What are the consequences of this? Now every time someone wants to use that API: What are the consequences of this? Now every time someone wants to use that API:
Line 75: Line 72:
   - KP realizes there are no docs. KP spends 2 minutes creating a docs page, writes down the answer, gives it to the user.   - KP realizes there are no docs. KP spends 2 minutes creating a docs page, writes down the answer, gives it to the user.
  
-Now the user has that docs page to share with anyone facing the same problem and KP can spend less time answering that question in the future+Now the user has that docs page to share with anyone facing the same problem and KP can spend less time answering that question in the future. This saves everybody time and improves morale. 
 + 
 +===== tools ===== 
 + 
 +I'm not going to talk about what docs tools I like here. Actually I am going to talk about the opposite. 
 + 
 +Maxim: 
 + 
 +<blockquote>Docs are worthless if nobody writes them.<cite>Me</cite></blockquote> 
 + 
 +Yep. You know how you get people to write docs? I can tell you that it is not by pointing them at a `docs/` directory with instructions to just make a PR. It is by making it as frictionless, painless, as easy as possible to edit the docs. This is triply true in organizations where people are not rewarded for writing docs. Which is most of them, at least in my experience. 
 + 
 +If I have to make a git commit to edit docs, the platform is DOA. If I cannot drag and drop a screenshot into the editor, the platform is DOA. If I have to learn a syntax to edit docs - even if it is Markdown - the platform is DOA. If it takes me more than 5 seconds or so to make an edit or add a screenshot or correct a typo, the platform is DOA. 
 + 
 +I say this as someone who built https://docs.frrouting.org/. These docs are, technologically, fantastic. reStructuredText is an amazing markup system for technical documentation and has rich structural capabilities with cross referencing, glossaries, syntax highlighting, parsers, et cetera. It can be compiled into any format you want - PDF, HTML, manpage, transpiled into almost any other markup. It's version controlled in git and as a plain text format you can use all the great tooling you use with code to view it, diff it, edit it. From a technical perspective it's really close to the best system out there. Yet the FRR docs are years out of date in most areas. Do you know why? It's because to edit these docs you need to: 
 + 
 +  - Know reStructuredText 
 +  - Make a git commit 
 +  - Submit a PR. 
 + 
 +That's it. Each of these things individually adds so much friction that when you put them in front of someone who is anything less than passionate about documentation, and isn't paid to write it, the idea of updating the docs is going to vanish from their mind leaving a spotless void that can be filled with code or a cocktail or any number of other things. 
 + 
 +Now put this person in front of a webpage with an clearly visible "Edit" button. That typo staring them in the face? All you have to do to fix it is click that button, delete that one extra `e` and click save. It costs nothing to do it and you get the instant satisfaction of contribution. 
 + 
 +Docs with low friction at least have a chance of tending towards becoming ground truth and references. Docs with high friction enter a self reinforcing cycle of decay. Nobody edits docs that are out of date. Nobody wants to polish a turd. But a fleck of dust on a beautiful object can motivate even the most depraved docs hater to brush it away.
  
-=== docs pitfalls ===+===== docs pitfalls =====
  
 Hitting these issues are also reasons why people form the opinion that docs are bad. Hitting these issues are also reasons why people form the opinion that docs are bad.
  
-== The docs are too detailed ==+==== the docs are too detailed ====
  
 I have seen "docs" that go into excruciating detail. Sometimes, like in formal API specs in safety applications, this is necessary. But for many products it is not, and it will cause many problems: I have seen "docs" that go into excruciating detail. Sometimes, like in formal API specs in safety applications, this is necessary. But for many products it is not, and it will cause many problems:
Panorama theme by desbest
documentation.1724889179.txt.gz · Last modified: by qlyoung
CC Attribution-Noncommercial-Share Alike 4.0 International Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International