Re: Documentation collaboration - best practices and tools used?

Subject: Re: Documentation collaboration - best practices and tools used?
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: Shawn C <shawn -at- cohodata -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 4 Nov 2014 10:03:50 -0800

Atlassian replaced wiki markup with XHTML three years ago, in
Confluence 4. Its XHTML source and WYSIWYG formatting options are
*very* similar to Flare's.

Whatever tool I'm using, I make do with the off-the-shelf formatting
unless it's absolutely unavoidable. In 18 months of working in
Confluence, I've defined one CSS class to deal with a bug in the PDF
output and three user macros to deal with bad page breaks, far fewer
than I had to define in Flare 7.1 (the last version I worked with).
Otherwise, the off-the-shelf formatting is completely adequate for my
purposes.

Using Scroll PDF Exporter, I get professional-looking PDF output,
better than I did with Flare.

Conditional content, I have "internal" flags that exclude topics from
PDFs that will be shared with customers and "exclude" tags for things
that are just for documentation purposes. When using Confluence as a
web server, you can display different sets of topics to different user
groups.

If I needed more complex conditional text, I'd look at Scroll
Versions, but that might be a deal-breaker for Confluence. If I needed
to assemble a bunch of manuals for a set of products from overlapping
fields by defining multiple TOCs for a pool of topics, I'd probably
use Flare, DocBook, or DITA.

Some of the plugins cost money, but you're already piecing together
your toolkit from multiple sources. "Free" software can cost more if
everybody ends up spending a lot of time dealing with clumsy
workflows.

On Mon, Nov 3, 2014 at 4:51 PM, Shawn <shawn -at- cohodata -dot- com> wrote:
> Of course, I may not know what I am I talking about, considering that my
> exposure is limited, however, my opinion is based upon the following
> observations:
> a) I have never any good examples of documentation that was both viewable as
> an HTML and downloadable as a PDF, and/or available as a ePub.
> Furthermore, I would still love to see one good PDF manual designed in
> Confluence.
> b) Editing and fine tuning content seems a lot more difficult in Confluence
> (wiki markup is more limited and time consuming than XHTML coding)
> c) How do you... set conditional content, build global content libraries,
> localization, customized bulleted lists, etc... nearly every 'extended'
> feature requires a plug-in and often these plug-ins are prohibitively
> expensive.
>
> That way I see it (and again, I am willing to admit that I don't know
> Confluence well enough), Confluence becomes a burden if your documentation
> requirements extend past the capabilities of 'cookie cutter' wiki markup
> language.
>
> But if I could accept Confluence's limitations, my documentation woes would
> suddenly become very easy.
>
> Love for you to tell me that I am completely wrong. :) Seriously.
>
> Thanks,
> Shawn
>
> On Mon, Nov 3, 2014 at 3:51 PM, Robert Lauriston <robert -at- lauriston -dot- com>
> wrote:
>>
>> What's your objection to drafting in Confluence? When your docs are in
>> a wiki, supporting multiple reviewers is pretty painless. I generate
>> PDF and web help directly from Confluence.
>>
>> My workflow is very simple:
>>
>> 1. draft and revise topics in Confluence to reflect changes in the release
>> 2. create JIRA issues for reviewers
>> 3. revise per their comments and clean up any edits they made
>> 4. go back and forth as necessary, tracking with JIRA
>> 5. when all JIRA issues for the release are closed, generate final doc
>> for release
>>
>> I hope I never have to go back to using an offline, non-collaborative
>> authoring tool.
>>
>> On Mon, Nov 3, 2014 at 3:29 PM, Shawn <shawn -at- cohodata -dot- com> wrote:
>>
>> > Ideally, I am looking for a collaborative tool that allows full editing
>> > and
>> > accepts PDF, HTML (with images) input...
>
>
>
>
> --
> Shawn Connelly
> Technical writer
>

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
Re: Documentation collaboration - best practices and tools used?: From: Robert Lauriston
Re: Documentation collaboration - best practices and tools used?: From: Shawn
Re: Documentation collaboration - best practices and tools used?: From: Robert Lauriston
Re: Documentation collaboration - best practices and tools used?: From: Shawn

Previous by Author: Re: [RMX:NL] Re: How do I do this [Word 2010]?
Next by Author: Re: Rollover TOC displays topics in Flare webhelp?
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