Why does Tech Writing matter?
Without tech writing, you'd be stuck reading code.
Events and talks inspire a few devs, at one time.
Good writing? Inspires tons of devs, over a long period of time.
Include a Narrative
- What's the problem you're solving?
- What problems did you face?
- What was your 'light bulb' moment?
Giving your post a narrative makes it easier to follow, and keeps your writing organized.
Use present tense
In your title, and probably in your post.
This helps readers relate, and engage, with your writing.
It also helps you think like your readers.
Use them, but a little goes a long way.
These get your reader really thinking about the subject at hand.
Challenge your readers
At the end of your writing, challenge your readers to take your example a step further, or include a call to action to check out your repository.
Cater to a wider audience
At an event, you can assume a specific skill level or background.
You can't do that as much with technical writing- you're reaching a much larger audience (hopefully!)
Set up the audience in your intro
Address what skill level you need to understand the tasks/ideas in your writing.
Make a clear statement as to what exactly you're covering- especially if your title is ambiguous.
Show them your environment
If you're showing code, list what version of the language, dependencies, what software you're using.
The reader should be able to easily figure out if something's different should the come across a problem.
Links, Links, Links
Dependencies, needed software, other tutorials - link to the information instead of trying to shove it into your own writing.
Put the links where they are relevant, or most useful; long download needed? Put that near the beginning.