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