3 ms·
You don't have to be Stephen King to write clear technical documentation for your fellow teammates. I think that people can learn some writing with practice (I
by js8 6y ago
You don't have to be Stephen King to write clear technical documentation for your fellow teammates.
I think that people can learn some writing with practice (I know because I did). But it's like with everything, if you don't practice, you will never learn. IMHO, this just stresses the importance of having culture where things are written down.
I suggest as a starting point, just write as if you were explaining the subject or code to somebody. Use full sentences, not bullet points.
- TeMPOraL 6y agoI think it's also important to have a culture of reading, not just writing. Otherewise, nobody will ever know if the writing is any good. It's like with backups - you don't actually have one until you've successfully restored your system from it. Onboarding is a good moment for testing a lot of internal documentation. Instead of getting a senior to help set up a new hire, give the newcomer a list of Wiki pages and see if they can set themselves up from it. If they struggle, you'll know what exactly needs fixing.
- sib 6y ago>> I think it's also important to have a culture of reading, not just writing. That's certainly part of the key at Amazon. Documents are written to be _read_ and _used_ in critical decision-making. If you regularly don't read the documents distributed at the beginning of meetings and then ask questions that are clearly answered in those documents, you will be "profoundly unsuccessful" at Amazon. (How's that for a euphemism?)