Re: Documentation collaboration - best practices and tools used?

Subject: Re: Documentation collaboration - best practices and tools used?
From: Ryan Young <ryangyoung -at- gmail -dot- com>
To: Lois Patterson <loisrpatterson -at- gmail -dot- com>
Date: Tue, 4 Nov 2014 10:37:04 -0800

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

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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


References:
Re: Documentation collaboration - best practices and tools used?: From: Shawn
Re: Documentation collaboration - best practices and tools used?: From: Lois Patterson

Previous by Author: Re: Large Documents in Word
Next by Author: Re: Large Documents in Word
Previous by Thread: Re: Documentation collaboration - best practices and tools used?
Next by Thread: Re: Documentation collaboration - best practices and tools used?


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


Sponsored Ads