The Technical Writers' Manifesto

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 guidelines.

Accuracy

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.

Clarity

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.

Entertainment

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.