Monday, May 27, 2019

Style Guides for Technical Documentation

While I don't want to get bogged down as we start this project, I would like to figure out what is the best practices for technical documentation... so as we start, lets just write... but I also want to explore some style guides and eventually settle on a style guide for the docs we use in this project... and make sure we stick to a "voice" and tone that is good for our High School and College learners.

Here are a few links I'm going to be looking at:


What style guides have you used?  What is your preferred "voice"? 

For general text  and instruction I like to try to keep the language in a directive or command form.  "Add the LED to the circuit, connecting the Anode (+) to pin 3 of the 555 timer and the cathode (-) to ground", rather than "You  can now add the LED to the circuit...."

I tend to favor more informal voice for "Note:" or "Pro Tips", where you use language and descriptions like "You will be more successful in this step if you...."

I would like to get your comments on what you have found to be successful, and if you have examples, please link them in the comments.

No comments:

Post a Comment