Technical Writing for Developers: Difference between revisions
(Created page with "Just be cause to instruct computers to do your bidding all day doesn't mean you should not spend some time learning how to communicate iwth humans well. This is an opinion pe...") |
|||
| (4 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
This is an opinion | aka "Tech Writing for Devs" | ||
Just because you instruct computers to do your bidding all day doesn't mean you should not spend some time learning how to communicate with humans well. | |||
This is an opinion piece. It's a collection of my opinions. | |||
This is a collection of notes about how to write well for those of us in Information Technology. | This is a collection of notes about how to write well for those of us in Information Technology. | ||
This | This document is therapy for all the shitty stuff out there that will never be fixed. | ||
== Documentation - Who, Where, and When == | |||
Should I document in code or in a wiki page or in a read me? | Should I document in code or in a wiki page or in a read me? | ||
| Line 13: | Line 16: | ||
Yes. | Yes. | ||
Different places and forms of | Different places and forms of documentation are appropriate and effective for different projects. | ||
'''readme for:''' | |||
* how to install | |||
* how to deploy | |||
* Dependancies | |||
* How to configure, command line options, env vars. | |||
* how to submit bugs | |||
* how to test | |||
* concepts | |||
'''"in code" for:''' | |||
* per function documentation. | |||
* not concepts | |||
* not how to install | |||
* not how to test | |||
'''wiki page:''' | |||
* architectural diagrams | |||
* Approach | |||
* scope | |||
* limitations | |||
* how to install | |||
* how to deploy | |||
* Dependancies | |||
* How to configure, command line options, env vars. | |||
* how to submit bugs | |||
* how to test | |||
* concepts | |||
* Links to dashboards | |||
* not to monitor | |||
* Logging | |||
== Acronyms == | |||
You should use them , but not too hard, and you should follow some guide lines. | You should use them , but not too hard, and you should follow some guide lines. | ||
Latest revision as of 17:11, 19 May 2022
aka "Tech Writing for Devs"
Just because you instruct computers to do your bidding all day doesn't mean you should not spend some time learning how to communicate with humans well.
This is an opinion piece. It's a collection of my opinions.
This is a collection of notes about how to write well for those of us in Information Technology.
This document is therapy for all the shitty stuff out there that will never be fixed.
Documentation - Who, Where, and When
Should I document in code or in a wiki page or in a read me?
Yes.
Different places and forms of documentation are appropriate and effective for different projects.
readme for:
- how to install
- how to deploy
- Dependancies
- How to configure, command line options, env vars.
- how to submit bugs
- how to test
- concepts
"in code" for:
- per function documentation.
- not concepts
- not how to install
- not how to test
wiki page:
- architectural diagrams
- Approach
- scope
- limitations
- how to install
- how to deploy
- Dependancies
- How to configure, command line options, env vars.
- how to submit bugs
- how to test
- concepts
- Links to dashboards
- not to monitor
- Logging
Acronyms
You should use them , but not too hard, and you should follow some guide lines.
The art of writing is quite old and is employed by various fields. Each field has it's own uances.
Some places you might look for gu8delines are:
- Legal Writing
- Acedemic Writing
- Scientific Writing
