Re: Documentation collaboration - best practices and tools used?

Subject: Re: Documentation collaboration - best practices and tools used?
From: Lois Patterson <loisrpatterson -at- gmail -dot- com>
To: shawn -at- cohodata -dot- com
Date: Mon, 3 Nov 2014 11:51:36 -0800

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








On Mon, Nov 3, 2014 at 9:49 AM, Shawn <shawn -at- cohodata -dot- com> wrote:

> Thank you to everyone for your contribution to this thread.
>
> Unfortunately, it seems that most of you didn't share your own workflows?
> How to do get SMEs to edit documentation? What are your workflows for new
> documents vs revising documents?
>
> Forgive me for possibly repeating myself....
> My big/huge problem now is that once I build content in Flare, I have no
> easy way of allowing SMEs to edit the document's content (full text
> editing, that is). This is causing me so much grief that there is a
> conversation about dropping Flare. I don't want this to happen because I'll
> lose a lot of Flare's advanced features.
>
> I really need a solution that will work in an environment where Windows OS
> is nearly non-existent.
>
> So far, I have exhausted a number of options, like:
> - Adobe Acrobat editing - cons: It doesn't allow easy full text editing
> (mostly suitable for short commenting)
> - Google Docs - cons: No way to *correct* convert a document to gdocs
> format
> - Confluence - cons: seems to only allow Word input conversion. I really
> only have HTML or PDF sources to work with.
>
> Someone asked to see my workflow swinlane... I have attached it... warning,
> some of the review process doesn't work so it is still a work in progress.
> Love to hear from others, your opinions and what works for you.
>
>
> --
> *Shawn Connelly*
> Technical writer
> <shawn -at- cohodata -dot- com>
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 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 loisrpatterson -at- gmail -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
>
>

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


Follow-Ups:

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

Previous by Author: Re: Large Documents in Word
Next by Author: Re: Post on the misconceptions about technical writing
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


Sponsored Ads