Technical Writing for Developers

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