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.
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.
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