Instructions for reviewers?

Post Reply
chuck_agari
Sr. Propeller Head
Posts: 225
Joined: Wed May 30, 2018 2:40 pm

Instructions for reviewers?

Post by chuck_agari »

I'm testing Flare & Central. I just invited a user as an SME, then from Flare, assigned that user a topic to review. In an existing topic, I added a "Test Section" with some specific instructions in that section, to highlight and comment on a couple of deliberately misspelled words.

I would have liked to have given those specific instructions--or any instructions--in the actual "assign to a user for review" process. It is not at all uncommon for a topic to be updated, one small section added or changed, and the change is all that needs to be reviewed. It's also not at all uncommon--and even necessary, as just about any experienced tech writer knows--to have to give explicit instructions to (some) reviewers, such as "ignore the grammar and focus on accuracy." So I'm wondering why being able to add instructions from author to reviewer ins't available.
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Instructions for reviewers?

Post by Nita Beck »

Whatever the review workflow -- whether involving Central or not -- I insert what I call "reviewer notes" directly into Flare topics and then style them with a generic style I call .Reviewernote. That style does two things in particular: One is that it makes the text a vivid color on a colored background, so the notes stand out. The other is that anything styled with that style is automatically conditioned as "ReviewOnly", which I exclude from production output. I also prefix all reviewer notes with "REVIEWERS:" to have the notes stand out even more. (And if I were really smart, I should have the CSS add that automatically, too, by using the "::before" attribute.)

I also use little snippetized "signposts" -- also styled with the .Reviewernote style -- that read "NEW"/"END NEW" and "REVISED"/"END REVISED" to frame those little bits that I want reviewers to focus on, instead of having to review an entire topic, for the exact reasons you give.

In short, I'm achieving what you're after with Flare functionality rather than Central functionality.

EDIT: It occurs to me that the vivid-colored text on a colored background might not appear in Central’s simplified editor. I’ll need to experiment some, but in the meantime, I can always frame my reviewer notes in square brackets and continued to use the “REVIEWERS:” prefix.

EDIT 2: I agree with you that it would be ideal for there also to be a way to add some overall comments to the notification that SME reviewers will receive from Central to alert them to a new review. Sounds like a good candidate for a feature request.
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
chuck_agari
Sr. Propeller Head
Posts: 225
Joined: Wed May 30, 2018 2:40 pm

Re: Instructions for reviewers?

Post by chuck_agari »

Thanks Nita, those look like some very interesting tips.

A FB friend who is using Flare on a team 4x the size of mine (that is, 4 people), said that she thought Central was overkill for her org, and that she just distributes PDFs. Kinda made me rethink whether Central was necessary where I am. So our plans are to to forward with Flare, but without Central. I think using your tips will make the process here better.

Thanks!
ChoccieMuffin
Senior Propellus Maximus
Posts: 2630
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: Instructions for reviewers?

Post by ChoccieMuffin »

chuck_agari wrote:Thanks Nita, those look like some very interesting tips.

A FB friend who is using Flare on a team 4x the size of mine (that is, 4 people), said that she thought Central was overkill for her org, and that she just distributes PDFs. Kinda made me rethink whether Central was necessary where I am. So our plans are to to forward with Flare, but without Central. I think using your tips will make the process here better.

Thanks!
We are a team of two here, with about a dozen assorted reviewers. Because of their priorities the reviewers all tend to do doc reviews towards the end of a project as we approach software release, so we would need to have lots of SME seats in Central, and you can bet the reviewers would whinge very loudly about having to use yet another tool. Instead, I have prepared a generic "Reviewing Guidelines" document telling them what they need to look for (that the content is factually correct, mainly) and how to add review comments in Acrobat. I know that means I then have to open their reviewed PDF and transfer their comments into our Flare files, but the standard of their writing means that I generally have to change their comments to adhere to our writing style guide anyway so even if we used Central I wouldn't generally accept their comments.

So that they know which bits to review and don't end up reading the whole thing if they're signing off a requirement, in our completely separate workflow tool (TFS) I add the titles of the topics that have changed when I pass the requirement to them for review. If it's something where a term has to change throughout, I don't bother (they can do a search in Acrobat). At least that way I don't have to add, and then delete, ReviewerNotes stuff in Flare as well as dealing with the content.

A clunky process, but it just about works.
Started as a newbie with Flare 6.1, now using Flare 2023.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
chuck_agari
Sr. Propeller Head
Posts: 225
Joined: Wed May 30, 2018 2:40 pm

Re: Instructions for reviewers?

Post by chuck_agari »

ChoccieMuffin wrote:
chuck_agari wrote:Thanks Nita, those look like some very interesting tips.

A FB friend who is using Flare on a team 4x the size of mine (that is, 4 people), said that she thought Central was overkill for her org, and that she just distributes PDFs. Kinda made me rethink whether Central was necessary where I am. So our plans are to to forward with Flare, but without Central. I think using your tips will make the process here better.

Thanks!
We are a team of two here, with about a dozen assorted reviewers. Because of their priorities the reviewers all tend to do doc reviews towards the end of a project as we approach software release, so we would need to have lots of SME seats in Central, and you can bet the reviewers would whinge very loudly about having to use yet another tool. Instead, I have prepared a generic "Reviewing Guidelines" document telling them what they need to look for (that the content is factually correct, mainly) and how to add review comments in Acrobat. I know that means I then have to open their reviewed PDF and transfer their comments into our Flare files, but the standard of their writing means that I generally have to change their comments to adhere to our writing style guide anyway so even if we used Central I wouldn't generally accept their comments.

So that they know which bits to review and don't end up reading the whole thing if they're signing off a requirement, in our completely separate workflow tool (TFS) I add the titles of the topics that have changed when I pass the requirement to them for review. If it's something where a term has to change throughout, I don't bother (they can do a search in Acrobat). At least that way I don't have to add, and then delete, ReviewerNotes stuff in Flare as well as dealing with the content.

A clunky process, but it just about works.
I should probably do something like that. About the only thing that I HAVE to tell reviewers is that they need to review in Acrobat Reader, not Preview. Turns out Flare has a bug where when you track changes, you get black rectangles of various sizes near or over your changed content in PDF outputs, but only when viewed in Preview. They look fine in Acrobat Reader.

What I ended up doing is creating a couple of "review" targets, each with their own TOCs. As I'm doing work on a Jira, the to[ics that I'm adding or changing I add to the review target TOC. I create an updated target output and attach it to the Jira before I put it in Review state. Yes, this means that sometimes the PDFs have content for multiple tickets, but I can live with that because SMEs aren't having to page through an entire manual. The only other minor annoyance is that while in the TOC, I create empty books for each ticket and put the corresponding topics in their respective books, the output doesn't show that book as any sort of divider, so the topics all run together.
Post Reply