Technical Writer's Guide
Our goal is to let our readers fully understand the IOTA technology and the community behind it. We provide only accurate information and convey it in a clear form with no room for misunderstanding. Our writing welcomes and encourages learning and reading. With this in mind, we shape our technical writer's guide.
An article of documentation is worthless if it is wrong. The reader cannot follow an instruction with errors, nor learn from explanations that distort reality.
Always check if what you have written is true. Check function signatures and return values. Run examples locally. Always ask a developer to check your work for errors.
There is no excuse for complex and confusing writing, especially when you explain complex and confusing subjects. Always write plain and simple without making trivial or patronizing statements. Your readers are smart, just learning.
Learning is exhausting, and readers are always tempted to do anything else. Treat them with fresh concepts and ideas — and the subject of your article offers plenty of them to share. There is place for humor, too, but keep it subtle: you want to keep the reader focused, and jokes are distracting.
The IOTA's writing guide is extensive — and also long. There are a few handy habits that could help you to write solid texts, even if they do not necessary follow the guide.
If you are stuck with a single prompt that just does not look right, leave it alone and finish the rest of the article. Leave it for tomorrow, if you must. Your brain will find a way to rewrite it, or you will find out that you can just remove the troubled piece.
Read your text out aloud. As silly as it sounds — and as silly as you sound, this reveals most issues with the current revision. Misspelled or skipped words become apparent, some prompts sound confusing with missed context or hang in the air without a proper ending or follow-up. You stop to draw breath in the middle of an overly long sentence, and a paragraph with too many hard breaks makes you stutter.
If you have troubles writing the first paragraph, write any sort of introduction or start writing from the middle. Starting is the hardest part, and you will always have a chance to cut trivialities or elaborate when you get momentum.
If nothing helps, put the article to review as it is and mention your issues in the pull request. Others might give you an idea.
You can break any rule — as long as your take would do the job better.