Re: Documentation collaboration - best practices and tools used?

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

Hello Lois,

Thanks for sharing your workflow with us.

Collaborator seems interesting (especially with its git plug-in) but I am
trying to understand how if that tool can link in with Flare. I still need
to publish good looking docs, so Collaborator is only good as an
intermediary tool. I think I will still have a problem synchronizing
content between Flare and Collaborator. Pity that it doesn't accept HTML
content.

>You could set up a similar workflow, but using DITA or Markdown.

The best looking Flare published docs are as PDF and HTML5. I'm not sure
how much work would be required to output a solid DITA document and
Markdown is not supported by Flare, beside it would result in too much loss
of fidelity.

Best regards,
Shawn


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
>
>
>
>
>
>
>
>
> 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>
>>
>>
> *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 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: Documentation collaboration - best practices and tools used?
Next by Author: Re: Documentation collaboration - best practices and tools used?
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