Differences
This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
| documentation [2024/08/28 23:52] – add lots more qlyoung | documentation [2024/08/29 00:16] (current) – 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, | + | 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, |
| - | + | ||
| - | === docs go out of date === | + | |
| - | + | ||
| - | Yes they do. But if this is a significant burden, you are probably doing one of these things wrong: | + | |
| + | ===== culture ===== | ||
| - | === culture | + | In a professional context, company |
| - | 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, | + | 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. |
| 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. | ||
| 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. |
| - | === 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 " | I have seen " | ||
