OT: peer review scheduling

Post by James Owens
It's off-topic, but this group is so quiet I hope no one minds.
Would you recommend scheduling a peer review with another writer on
completion of each topic, each chapter, or each book? Our team has yet
to reach a consensus.

What does this peer review consist of?

Who/what is the team you are talking about?

What are the manuals about and what audience are they written for?

Post by James Owens
--
"For it is only of the new one grows tired. Of the old one never tires."
-- Kierkegaard, _Repetition_
James Owens, Ottawa, Canada

James Owens

2005-03-10 03:12:32 UTC

What does this peer review consist of?

That's a good question. The review is to ensure good writing that adheres
to the style guide; thoughtful information design; consistency between
related topics, and lack of redundancy; and technical accuracy, to the
extent possible among the writing group.

Post by l***@nospam.net
Who/what is the team you are talking about?

We have a team of four writers.

Post by l***@nospam.net
What are the manuals about and what audience are they written for?

They are operator and administrator manuals for a software product.

--
"For it is only of the new one grows tired. Of the old one never tires."
-- Kierkegaard, _Repetition_

James Owens, Ottawa, Canada

l***@nospam.net

2005-03-10 04:28:24 UTC

What does this peer review consist of?

I'm old school; e.g., I was a writer and editor before any school anywhere in the world was selling degrees in technical writing, so I have the idea you need to develop a style guide and live by it. If you guys have questions about consistency and accuracy levels there is something wrong with the style guide. Or you need a tougher editor, with the Chicago Manual of Style on his brain. Groups also need to develop a project outline and work by it. In some industries that means understanding the audience and what they need to do with the product, as well as documenting the technical features. --For the most part, the software industry still doesn't get that, but users aren't demanding more either.

Post by l***@nospam.net
Who/what is the team you are talking about?

We have a team of four writers.

Do you guys get along, or is there one who is marching to a different drummer -- and causing a rift leading to your questions here?

Post by l***@nospam.net
What are the manuals about and what audience are they written for?

They are operator and administrator manuals for a software product.

The software writing industry will someday find what the writing department in other industries found years ago; The writers have to understand the product, and how its used. That knowledge makes the manual cost more, but in the end its the only way you step beyond documenting menus and features.

In what I've said, I'm also assuming that your programmers also understand the product and how the code works, and that they can explain it to the writers with something more detailed then "its magic."

Post by James Owens
--
"For it is only of the new one grows tired. Of the old one never tires."
-- Kierkegaard, _Repetition_
James Owens, Ottawa, Canada

James Owens

2005-03-10 10:52:59 UTC

Post by l***@nospam.net
What does this peer review consist of?

I'm old school; e.g., I was a writer and editor before any school

anywhere in the world was selling degrees in technical writing, so I have
the idea you need to develop a style guide and live by it. If you guys
have questions about consistency and accuracy levels there is something
wrong with the style guide. Or you need a tougher editor, with the Chicago
Manual of Style on his brain. Groups also need to develop a project
outline and work by it. In some industries that means understanding the
audience and what they need to do with the product, as well as documenting
the technical features. --For the most part, the software industry still
doesn't get that, but users aren't demanding more either.

We have a style guide, but it's a work in progress. For the most part we
adhere to the MS Manual of Style for Tech Pubs. Rather, we seek to do so;
it help to check each other'w sork

Post by l***@nospam.net
Who/what is the team you are talking about?

We have a team of four writers.

Do you guys get along, or is there one who is marching to a different

drummer -- and causing a rift leading to your questions here?

Two of the writers are very new -- less than three months. Between us
have three opinions about when to do peer reviews. (The fourth writer is
updating the template.) But it's a civil disagreement -- we're trying to
research what's best. Do you have advice about when to schedule peer
reviews?

Post by l***@nospam.net
What are the manuals about and what audience are they written for?

They are operator and administrator manuals for a software product.

The software writing industry will someday find what the writing

department in other industries found years ago; The writers have to
understand the product, and how its used. That knowledge makes the manual
cost more, but in the end its the only way you step beyond documenting
menus and features.

Post by l***@nospam.net
In what I've said, I'm also assuming that your programmers also

understand the product and how the code works, and that they can explain
it to the writers with something more detailed then "its magic."

--
"For it is only of the new one grows tired. Of the old one never tires."
-- Kierkegaard, _Repetition_

James Owens, Ottawa, Canada

James Owens

2005-03-10 11:28:30 UTC

(sorry about the unusual quoting -- your paragraphs appear as a single
line in my reply, so I wrap them, but then there are no '>' characters at the
start of each wrapped line. I've used tag-style markup: <Letour> </Letour>.)

Post by l***@nospam.net
What does this peer review consist of?

<Letour> I'm old school; e.g., I was a writer and editor before any school
anywhere in the world was selling degrees in technical writing, so I have
the idea you need to develop a style guide and live by it. If you guys
have questions about consistency and accuracy levels there is something
wrong with the style guide. Or you need a tougher editor, with the Chicago
Manual of Style on his brain. Groups also need to develop a project
outline and work by it. In some industries that means understanding the
audience and what they need to do with the product, as well as documenting
the technical features. --For the most part, the software industry still
doesn't get that, but users aren't demanding more either.
</Letour>

<James>
We have a style guide, but it's a work in progress. For the most part we
adhere to the MS Manual of Style for Tech Pubs. Rather, we seek to do so;
it help to check each other'w sork
</James>

Post by l***@nospam.net
Who/what is the team you are talking about?

We have a team of four writers.

<Letour> Do you guys get along, or is there one who is marching to a different
drummer -- and causing a rift leading to your questions here?
</Letour>

<James>
Two of the writers are very new -- less than three months. Between us
have three opinions about when to do peer reviews. (The fourth writer is
updating the template.) But it's a civil disagreement -- we're trying to
research what's best. Do you have advice about when to schedule peer
reviews?
</James>

Post by l***@nospam.net
What are the manuals about and what audience are they written for?

They are operator and administrator manuals for a software product.

<Letour> The software writing industry will someday find what the writing
department in other industries found years ago; The writers have to
understand the product, and how its used. That knowledge makes the manual
cost more, but in the end its the only way you step beyond documenting
menus and features.

In what I've said, I'm also assuming that your programmers also
understand the product and how the code works, and that they can explain
it to the writers with something more detailed then "its magic."
</Letour>

--
"For it is only of the new one grows tired. Of the old one never tires."
-- Kierkegaard, _Repetition_

James Owens, Ottawa, Canada

Paul Goble

2005-03-10 17:22:48 UTC

Post by James Owens
<James>
Between us have three opinions about when to do peer reviews.
</James>

There may not be "a" best answer. Why not allow each writer to
get a review when they feel ready for one? Some of my (very able)
colleagues work by finishing a topic or chapter at a time, others
work a little here and a little there until the whole book reaches
a finished-enough-for-review state all at once. It helps if everyone
has an "I'll drop everything to help you whenever you ask" attitude.

You might also consider separate reviews for different purposes.
For example, when I'm new to a style guide, I might want to review a
chapter for style guide compliance as soon as it's finished. That
allows me to avoid repeating the same mistakes. Reviewing a small chunk
at a time can also be less fatiguing for the reviewer.

On the other hand, it helps to have the entire book before me
when I review for stylistic consistency and factual completeness.

In my experience, apprentice writers often need topic-level reviews
at the beginning. As their ability grows, they eventually reach a
point where they know which books would benefit from a quick peer
review, and which ones can go out the door with just a subject-matter
expert review.

By the way, recently there have been dozens of messages regarding peer
reviews over in bit.listserv.techwr-l. Note that the newsgroup just
echoes a mailing list, and that anything you post on the newsgroup will
not be visible to the list subscribers.

Paul

James Owens

2005-03-10 10:54:21 UTC