TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
-Ryan
On Mon, Nov 3, 2014 at 11:51 AM, Lois Patterson <loisrpatterson -at- gmail -dot- com>
wrote:
> 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
