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 [2026/02/12 01:56] – [Tools] e qlyoungdocumentation [2026/02/12 17:05] (current) – [Tools] promote heading one level qlyoung
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, I will double down and claim 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.
  
 ===== culture ===== ===== culture =====
Line 74: Line 74:
 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. 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 ====+===== tools =====
  
 I'm not going to talk about what docs tools I like here. Actually I am going to talk about the opposite. I'm not going to talk about what docs tools I like here. Actually I am going to talk about the opposite.
Line 94: Line 94:
 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. 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 in front of this person a webpage with an 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.+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 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.
Panorama theme by desbest
documentation.1770861377.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