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:56] – more cleaner 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 46: | 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, |
| ===== culture ===== | ===== culture ===== | ||
| - | 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, | + | 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, |
| + | |||
| + | 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 68: | 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 ===== | ||
documentation.1724889398.txt.gz · Last modified: 2024/08/28 23:56 by qlyoung
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International