Requesting a Technical Writer

While technical writers are always up for a quick chat, they need to plan ahead for substantial contributions. You might need to document a new feature, amend an article, or write a new one.

Plan Ahead

The technical writing team takes up to two weeks to produce a text. In that time, writers research the topic, rework your draft or write an article from scratch, review and edit their commission, all while processing multiple other requests. In exceptional circumstances technical writers could work against a twenty-four-hour deadline, but keep in mind that this would put all other requests on hold and strain technical writers. Plan ahead, contact writers early, and respond swiftly. This is the smoothest way to get your project well documented.

Do Your Homework

Make sure that you did your homework before making a request. Decide what a writer has to do for you. Think about how could you help. As always, feel free to reach out to a writer if you need advise.

Prepare an Issue

If you do not have a fitting GitHub issue yet, create it in your project's repository and tell what writers have to do in the description or in the comments.

Either use your feature branch or create a new branch with the docs/ prefix. Commit all information that you have collected, be it drafts, prompts, or weblinks. You could place it directly in the documentation file to change, or inside the documentation/docs/in_progress directory. If you use external resources like Miro or Google Docs, add links in a text file, too. It is easier to write when you have everything in one place.

Do not forget to push.

Contact Writers

Tag the @iotaledger/tech-writers team in the issue's description or in the comments. Reference the working branch and mention where to look in it.

Review the Commission

Technical writers will turn to your expertise through the whole process. Even more, you are the final judge of their work. Read it carefully, make sure that it provides all necessary information, provides only true information, has no ambiguous meanings, and presents your project in its true spirit.

Technical writers will notify you when their commission is ready for a review.

Merge

Once you and the technical writers approve the commission, merge it. Technical writers have no writing access to your repository.

If you wish, you can squash your branch to remove intermediate drafts from the git history.