content-o-tron
content-o-tron copied to clipboard
rust-community
Rust technical reviewer signup
The shorten url to this issue is https://bit.ly/cot-halp
Please add a comment if you’re interested in becoming a technical reviewer for future rust blog posts.
@Amanieu could you please review this draft in this blogging assistance request: https://github.com/rust-community/content-o-tron/issues/61
Thanks!
@booyaa can you clarify in the top comment the intended role of a technical reviewer? Will there be additional kinds of reviewers? Are there other things that technical reviewers should comment on?
@aidanhs re: roles - I'll setup a task to define the roles better.
In essence, for a technical reviewer, we'd expect someone with experience of using Rust, at a later date we'd like to have people who have specialised knowledge: compiler, language design or is active in the working group areas.
Given that you've worked with actual technical reviewers, is there anything else I need to consider?
@booyaa so perhaps I can better ask the question by asking what a technical reviewer will not do.
For Docker in Practice, Manning had three separate editors:
- development editor, to monitor the progress of the book and make sure it follows the general expected theme, has a mostly acceptable flow and is moderately readable (we didn't get much feedback here because me and my coauthor were generally ok at this stage)
- technical editor, to read through the book and make sure there are no technical mistakes
- copyeditor, to make sure the book fits the 'house style', has correct spelling, makes sure it's 'internally consistent' (e.g. if I mention a library, I shouldn't then vary and also call it an SDK, or if I mention some other part of the book, that part should actually be present)
For example, I was browsing through a post and I noticed some grammar/sentence errors and so on. Strictly scoping a technical reviewer to be the 'technical editor' above would not pick up these (it would come as part of copyediting). They would also not make suggestions on how reordering the post could make it flow better and so on. Instead, their focus would purely be on "is this post technically correct".
Bundling all three of these together could turn a 15min job into 2 hours (particularly if the English skills aren't so strong). I'd suggest just clearly setting expectations for both what would be expected from a reviewer/allow reviewers to specify what they're willing to do, and what reviewees can expect from a review.
For example, as a reviewer I might say: "I am willing to do either 'technical editing' or a full run of 'development editing', 'technical editing' and 'copyediting'. I anticipate being able to do three technical editings per week, or one full editing."
If you had a couple of people like this, you might say to reviewees: "If you want a pure technical review, you can expect to be waiting a couple of days. If you want a full technical review, that may take a couple of weeks."
As a concrete example, in https://github.com/rust-community/content-o-tron/issues/61, @Amanieu has done both technical editing and copy editing, as requested by the reviewee - but some technical reviewers may not feel like doing this.
It also occurs to me that review time/willingness also somewhat depends on size of article - if you said 6xsmall == 2xmedium == 1xlarge, then you can have a fast-track for smaller articles (if you wanted) or allow people with limited time to restrict their involvement.
@booyaa I don't envy you having to define and keep track of all this! But maybe going all-in is overkill to start, up to you.
@aidanhs @Dylan-DPC @Amanieu if any of you are interested, someone's asked for some feedback on their exists posts. There's quite a lot, so feel free to review the most recent post(s).
#67