Doc Reviews and Reviewers


#1

Cross-posting from the general slack channel. Can y’all please describe briefly how you set up doc reviews? Specifically (the first two are most urgent for my immediate purposes):

  • Who do you ask?
  • Who do you consult with when putting together a list of reviewers? Or do you do it just yourself?
  • What kind of a review schedule do you provide, if any?
  • How much guidance, again if any, do you provide to your reviewers? (For example, asking tech reviewers not to review for style or tone if you’re at the draft stage of things. Or asking marketing not to touch tech content if you want their feedback on tone.)
  • How do you set up reviews? Do you provide the final deliverable (say, posting HTML on github pages)? Various deliverable types for review only (say, Word docs because track changes/reviewer comfort)? Do you provide a schedule for feedback in series? In parallel? Do you set up a meeting with all your reviewers to go over comments in real time? (I have done all of the above for different projects at different stages of doc production …) Set up a chat room? Get comments back in github issues/email/inline comments/something else?

Partial replies welcome – I’ve just tried to give you an idea of the kind of thing I’m interested in here. Thanks!

(p.s. TIL topic titles have a minimum length of 15 characters. :shrug:)


#2

I ask my peers, with each writer assigned a buddy for reviews.
Reviewers are agreed in advance.
Schedule depends on the dev cycle.
Definitely dictate what sort of review is needed.


#3

Now you’re speaking my language! I’m the Knowledge Base Administrator at BCIT, a polytechnic institute serving 50,000 or so students per year and 2900 faculty and staff. Our KB covers a wide variety of topics from logging into wireless, to printing, to using Cisco phones, to using the CMS to publish to the public website, to grades submission, to running Continuous Service Improvement projects, and on and on. We document software, hardware, and processes.

We have two people assigned to each article/document, if possible. One is the Content Owner and one is the Subject Matter Expert. The Content Owner, to start with, is usually the original author of the document. The SME is a sort of back-up - someone to go to who likely has the knowledge necessary to assess whether the document is still current, accurate, and relevant or not if the CO is unavailable, has left the Institute, is on vacation, etc.

I suggest a default review period of nine months for all articles, unless there’s a specific reason to do one sooner than that. Nine months between reviews moves the review through the school year, which may help to showcase deficiencies because of the different contexts that occur. It also is just short enough to catch things before they’re a major problem and long enough to let people feel like they’re getting away with something and really should review that thing now.

We have several different knowledge repositories in various places to deal with different needs, but there’s one record-keeping system that keeps track of all of the metadata for all the documents - what article belongs to whom, when it’s next due for review, and all of the correspondence we’ve had about it. It’s a part of our ticketing system, so we also have it set up so that users can report problems and that can open a task on that Knowledge Article to fix a problem.

When the review date happens, one of two things can happen, depending on who the Content Owner is. If they’re a member of the group with access to the ticketing system, they get assigned a task to review the article which goes into the same queue as all other tasks assigned to them within that system. If not, they get sent an email, two which they must reply.

Either way, I get a notice back from them that tells me the article is either okay as is, should be retired, or needs to be changed in some way. If the article is no longer necessary, I delete it from whichever repository it resides in. If it needs to be changed either I or the Content Owner (depending on the system) will change it. If it’s fine, I just update the next review date and the cycle begins anew.

Sometimes Content Owners leave. Then I have to hunt down a new owner. This is the most fun (read “least”) of all the tasks! People are rarely eager to take on responsibility for someone else’s work. Fortunately, I have an established culture to support me, and people like having the resource to refer people to, so usually it’s not a huge problem. Where occasionally I can’t find anyone, I get to start making ultimatums about how it can’t stay in the repository if a content owner isn’t assigned to it. I’ve deleted a few, but mostly someone steps up.

I keep track of something I call the “Reviewed Rate”. Basically, this is the active articles/documents in the system whose review date is in the future, as a proportion of the whole. Nowadays I try to keep it above 80%, though we once got as high as 90% (that was a red letter day). I think at the moment, due in part to articles coming due over the holidays, we’re around 72%, which means I’m emailing people, especially those that have more than one article overdue or those whose article has been overdue for a while. They get one polite and friendly email to them personally. If they don’t respond, they get a second polite and friendly email two to three weeks later that ccs their manager. That generally works.


#4

We use the same system that our devs use for their reviews, Atlassian Stash. I have some reviewers that I count on, usually QA (since they give final approval before we release our docs). I have some reviewers that I notify essentially as “info only” such as PMs, support and sales engineers.

We have no designated SMEs – I usually add the devs who did the underlying work.


#5

Caveats: I’m the lone tech writer for an enterprise software startup, and most of the docs are how-to/tutorials, examples, best practices.

I identify the primary and secondary subject matter experts (SMEs). The primary SMEs are the people who I work with to write the docs, and those are my primary reviewers. Since this is a small company, that’s usually 1-2 people. When I have a doc ready for review I get them into a meeting room and we go through the document together. (Some of them travel a lot, and they’ve agreed to review docs while on the plane; even if they do that I’ll have a review meeting after I incorporate their comments.)

I don’t give them guidance: I appreciate any and all comments, and it’s my job to decide what to include. If primary reviewers give me contradictory comments we resolve them in the meeting.

For secondary reviewers, I’ll send them a copy (people seem to like Word with review tracking turned on) and ask for comments within a week. I get a lower response rate on those, so I’ll send them reminders but I won’t hold back the docs if the secondary reviewers are late.

Basically: email is a black hole, meetings are better, and making someone review your doc while they’re trapped on a plane also works.


#6

I like to get at least the developer and the product manager, and the development manager too if I can.

I don’t limit what I ask for, but I do insert specific questions in the text for reviewers to answer, in order to focus their attention on key points.

I also ask them not only for feedback, but for signoff. That is, I ask them to take responsibility for the accuracy, suitability, and completeness of the docs. This tends to improve their attention to the document. It also suggests that their signoff is necessary for the release to proceed. This is not necessarily true, but I don’t tell them that.

One downside of this is that they will sometimes withhold signoff unless you include something they think is important but that you do not think should be in. In these case, I ask them: “What would the user do differently if they knew this?” The form of this question is vital. Don’t ask “Why does the reader need to know this?” Ask what they would do differently if they knew. It makes all the difference in making your case for what does and does not belong. And, of course, if they have a good answer, then it really should be in.


#7

I really love working with peer review system. We started implementing it at custom essay ltd last year and I and fully satisfied with it.