XML Doc Review -- WAS: Documentation collaboration - best practices and tools

Subject: XML Doc Review -- WAS: Documentation collaboration - best practices and tools
From: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 4 Nov 2014 23:16:10 -0800

I'm branching this off because I think it's a special situation... When documenting in XML, how do you handle doc review? A few possibilities are:
* Generate PDF and deliver review copies
* Generate HTML and post to a "review" site
* Review the raw XML
* Other?

Where I work the situation is very similar to what Lois describes below, only we use DITA. The docs are part of the product source, and they are automatically visible whenever the product gets built. At first I just committed doc changes, and the daily build would get them out for all to see as HTML. Then we switched to a review process using ReviewBoard. Since the docs are in the code repository, I must also have a review before I can commit -- a major bummer for my work flow. Now I generate a PDF for the subset that needs reviewing, and post that via ReviewBoard -- and commit after people say it's ok (which can take a while).

One thing I noticed is, nobody wants to review raw XML. So if your source is XML, what is your work flow?

Lois, thanks for sharing this workflow. We are moving to DITA and we are
going to have to rely on developers and SMEs to contribute much of the
content. So this workflow sounds like a potentially good model for us.

What does your SVN repository structure look like? We are trying to
understand how to set up our git repository. Right now, each dev team has
their own repository that includes a "docs" directory. We're thinking that
we could set up a separate docs project or repository and pull in topics
there using DITA maps to assemble the topics into a guide (or whatever) and
generate the output (this would all be scripted). Very interested to hear
how you handle the assembly and generation part of the workflow.


On Mon, Nov 3, 2014 at 11:51 AM, Lois Patterson <loisrpatterson -at- gmail -dot- com>

> I sympathize with what you are saying. Allowing (potentially) everyone
> direct access to the text and allowing everyone (potentially) to be part of
> the code review process is essential at my workplace.
> We have a workflow like this:
> Author (may be an SME or may be a technical writer or may be a developer)
> checks out a branch in SVN and writes the first draft, commits to SVN, and
> uploads to Code Collaborator. The content is authored in our particular
> version of XML, and is considered code.
> Several people (including at least one technical writer and at least one
> SME) are added to the code review.
> The content, after revisions, passes code review.
> It is merged into the trunk.
> The product is automatically rebuilt (using build scripts), and all of the
> content, including the newly added material, is regenerated (in HTML and
> PDF formats with XSL:FO and a few other things).
> With this method, everyone can use their preferred editor (it's emacs for
> some people, Notepad++ for others, and Oxygen for the technical writers),
> and no one is locked out of revising the text. The main problem I have with
> it is that small changes have to go through this cumbersome process, and I
> don't have as much control over output formats as I would like. The "owner"
> of a branch can allow anyone to work in that branch.
> You could set up a similar workflow, but using DITA or Markdown.
> Lois Patterson

Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l


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-leave -at- lists -dot- techwr-l -dot- com

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

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Previous by Author: Re: Is the STC worth it?
Next by Author: Re: Self-editing
Previous by Thread: RE: Rollover TOC displays topics in Flare webhelp?
Next by Thread: Re: XML Doc Review -- WAS: Documentation collaboration - best practices and tools

What this post helpful? Share it with friends and colleagues:

Sponsored Ads