We all know that the quality of our documentation and the process for getting articles ready for production are very important. Recently, we moved the technical writer position to Support Ops, with the goal of providing tech writing services for all devtools products and achieching scale. In practice, this change means that we need a new process. But before that, some context.
Until recently our approach to collaboration with technical writers was to prepare text draft and assign it to Desi, for what would often turn out to be a complete rewrite. During complete rewrite however, parts of the technical meaning could get lost, which often lead to one more iteration with the individual that is writing the article. While this approach worked when the scope was specific product or two, it won't work for the bigger organization.
With this previous experience in mind, a characteristics of process that could work at scale and reinforce positive feedback loop are:
- no bottlenecks, i.e. one person responsible for rewriting aticles
- usage of tooling that allow reviewers to efficiently provide feedback
- the mechanics of incorporating the feedback should be done by authors
The proposal that we think would solve those requirements is to use pull request when working on a doc aritcle and request review from the @docs-reviewers team on github. The @docs-reviewers team will use the tools provided by the pull-request UI to initiate a feedback discussion, after which it is responsibility of the pull request author to add and commit the changes. The goal is to initiate positive feedback loop that will help us all learn how to do writing better. If the work is bound to a specific deadline please provide this info inside a comment in the pull request.
Which article is important or popular? Use your best judgement and the existing data and/or consult with colleague.
For all other tasks please resort to the style guide that we already have .
When working on:
- new complex article or one about common problem for our user base
- article in which you are not certain about the content, format, use of language
- existing article that is very popular
- existing article that consistently receives low rating
The @content-edit team consists of Dimo, Kaloyan, Yordan and Desi.
We will try this approach for month or two and then evaluate our success so far. (number of pull requests + feedback).
Please drop me a line on Teams if you have any comments, otherwise, let’s give it a try.
Good candidates for pull request reviewing may also include:
What do you think?
On a side note, I agree with Kal's email comments.