Developer's Guide
Developers rarely revel in reading documentation, let alone in writing it. Writing documentation is hard, and it is even harder to write a captivating one. Luckily, IOTA has a team of dedicated technical writers. We can help you, and you can help us. This document explains how.
You are the author of your code. It makes you the original source of knowledge, the most reliable and often the only one. Technical writers cannot replace you or let you forget about the documentation. Quite the opposite, we want you to always keep it in mind so we could support you and make sure that users and other developers enjoy learning about your work.
This document will evolve as we invent more ways to help each other. Check for updates once in a while.
Make a Friend#
If you have not gotten in a contact with a technical writer yet, do it! We can advise you, ask the right questions, and plan together. Reach out to us through Slack DMs, #dev-documentation Slack channel, or via e-mail. If you come from outside IOTA, check the Team page for the external contacts.
Active technical writers:
- Aleksei Korolev
- Charles Thompson
- Lucas Tortora
- Sebastian Heusser
Do Your Homework#
IOTA employs dozens of software engineers who work across a dozen and a half of products and research projects. And there are four technical writers. On an average week, only one could attend to your project, and only for a day or two. The major bulk of the work is on your shoulders.
The most consuming part of writing is not the writing itself but the research of the subject. You have to gather bits of knowledge, structure it, and decide what is worth mentioning and what not. Then you put it into words, draft up an article, rewrite it clean, let others review it, and publish your work. The more you can do by yourself, the faster your project will get documented.
Some tasks you can manage on your own. For some you would need advice. Some tasks are better left to technical writers. Contact the writers' team and distribute the effort early.
To help you help us, we have prepared a toolbox, a collection of tools and tips for developers who write documentation.
Do Your Work#
An API reference already has a structure. Each function gets its own entry. Every entry has a few fields. Every field needs only a sentence or two. Yet you need to understand the code in depth: programmers write better API references than technical writers do.
Feel free to ask a technical writer for an advice or a review.
Make It Official#
Once again, we are up for a chat. But there are more projects than there are technical writers, and we need to plan ahead for any substantial contribution. See Requesting a Technical Writer for details.