Re: SMEs/QA don't have time to review the documentation

[voxwoman <voxwoman -at- gmail -dot- com>]

I don't recognize your name, but you could be working here with us, I'm
sorry to say.

Do you have a manager that can go to bat for you? Your developers are not
going to ever have time to review your documentation unless THEIR management
puts it into their schedule. So the chain of command all needs to buy into
the concept that having good documentation is as important as the product
and that they are willing to commit resources for that to happen.

I have yet to see that happen at my current job, but we're working on it. At
other places, when developer management was actually reasonable, and the
documentation was split appropriately among all the developers, a threatened
table top review (if they didn't email me comments beforehand) usually got
results.

Since you are not embedded within the development team, you are likely going
to have to go up the corporate org chart to the manager that has
responsibility for both development and documentation and convince THAT
person. Because he/she is the only one with the power to get the SMEs to
devote time for reviews.

Good luck!
-Wendy

On Fri, May 30, 2008 at 8:23 AM, SB <sylvia -dot- braunstein -at- gmail -dot- com> wrote:

> I would like to know how you are getting the material when doing the
> technical writing and how it should be done.
>
> Some of the teams have to be chased senseless. They never have the time for
> technical writing. They always dump the reviews on the same one or two
> people instead of splitting the chapters among a few people who end up
> really resenting this and end up not cooperating.
>
> This is what happens with us:
>
>
>   1. An update is planned. If I am lucky, I get a spec but a lot of it does
>   not target the user.
>   2. I have to review all the GUI windows and run them, one buy one because
>   it always changes. Sometimes changes are minor, sometimes major. There is
> no
>   system that keeps track of deltas.
>   3. I also have to review each CLI command and syntax one by one because
>   there isn't really a system that provides the deltas. There are hundreds
> of
>   commands.
>   4. Many times, I can't get a system on which I can run things because
>   there are not enough of them. So, I can just look at things. Sometimes it
> is
>   hard to reflect what a feature is actually doing.
>   5. If I am lucky, someone sits with me for a bit.
>
>
> Because our documentation is very big (some projects are close to 1000
> pages) and there are a lot of releases, this can be really overwhelming.
>
>
>   1. Then I send a review. Because there are so many changes between
>   versions, it is really hard to just highlight a section. Most of the
>   document, if not all has to be reviewed.
>   2. The SMEs don't have the time to review or when they do, they often
>   annotate with questions or comments without providing actual content or
>   corrections or sometimes what they write is not necessarily clear. As a
>   result, subsequent meetings are required, which takes even more time.
>
> I have always done my best to do it all by myself, assuming as much writing
> as possible and leaving just the review to the SMEs who do not provide true
> contents. However, at this point, I am collapsing, working around the clock
> 24/7 and the SMEs don't have the time to review despite the theoretical
> planning. With some of the teams, it is a major struggle because there are
> always crises and nothing is planned as an alternative excuses of all
> kinds.
>
> I believe that one of the problems is that R&D does not own the contents
> and
> does budget for the documentation, not to mention the reviews.
>
> The company is growing and so is the technical writing team and we have to
> deliver and am really frustrated at the way things work with some of the
> teams. I would like to know how things are done in your company and what I
> can do to improve the process. Do you have an established procedure?
>
> Should the SMEs review and prepare the manual and provide all the screen
> captures and information before I review the document?
>
> It has gotten to a stage beyond what a human being can tolerate and I would
> like to be able to get this back under control without having to quit (by
> the way, we are not compensated for overtime). A new technical writer will
> start in about a week, so now we will be three. However, that will not fix
> the review process. Maybe you have some advice? Some procedure
> improvements?
>
> Thanks in advance for your feedback,
>
> Syliva
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Create HTML or Microsoft Word content and convert to Help file formats or
> printed documentation. Features include support for Windows Vista & 2007
> Microsoft Office, team authoring, plus more.
> http://www.DocToHelp.com/TechwrlList
>
> True single source, conditional content, PDF export, modular help.
> Help & Manual is the most powerful authoring tool for technical
> documentation. Boost your productivity! http://www.helpandmanual.com
>
> ---
> You are currently subscribed to TECHWR-L as voxwoman -at- gmail -dot- com -dot- 
>
> To unsubscribe send a blank email to
> techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
> or visit
> http://lists.techwr-l.com/mailman/options/techwr-l/voxwoman%40gmail.com
>
>
> To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
> http://www.techwr-l.com/ for more resources and info.
>
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info.