Getting FLOSSy: Acrobat Killer Or HAT Replacement?

FLOSS Manuals: The OTHER FM for PDFs

Some writers truly hate Adobe Acrobat and any tool that can do the job better is worth a shot, particularly if it’s open source and easily navigated. Flossmanuals.net introduces FLOSS which does a lot of the single desktop Acrobat Pro’s job - collaboratively and open source.

Could FLOSS be the new Acrobat Pro killer?

FLOSS could bridge the gaps between Subject Matter Expert (SME) authoring of content and true documentation. For the specific purpose of supporting open source collaborative efforts this is heaven sent. Most open-source dev teams are simply not able to have those wonderful team meetings for doc review either for financial or time management purposes.

Update: Anne Gentle’s site talks about an event called a Booksprint that FlossManuals.net is doing for technical writers in support of open source programs.

I’ve been reading Janet Swisher’s review of FLOSS Manuals. She examines the pros and cons of Wiki briefly and explains the problem / solution of FLOSS definitively:

You can write documentation using an open source word processor like OpenOffice.org Writer, but you still need a content management system of some kind to handle versioning of drafts and communication within a project community, and CMSs are complex to set up and maintain.

And so a divide has emerged, with open source programmers on one side, wishing somebody would come help write the docs, and potential writers on the other side, too intimidated or too busy to learn the tools to work on open source projects.

FLOSS Manuals bridges that divide, and does so in a way that is deeply rooted in the open source ethos of community and collaboration.

FLOSS and Wikis for Documentation

The implementation and administration of the wiki model always seems to be the insurmountable challenge, if one is to be found. Janet has a solid point regarding Stewart Mader’s viewpoint on wikis for documentation:

I’ve generally been skeptical of wiki advocates who say, “Oh yeah, and you can create documentation in a wiki, too”, because I’ve seen very few actual examples.

Janet’s link refers to an article by Stewart Mader regarding the specific issue of documentation within a wiki. This happens to be an area where Stewart Mader and I disagreed earlier this year. I haven’t heard of many live wikis truly impacting technical writing and Janet confirms this from her perspective as well.

I’m happy to report that Stewart, Janet, and I technically all win on this point.

FLOSS Manuals IS a wiki, but it’s purpose-built for creating documentation. Its founders have created an open-source standard of documentation that blends reading, writing, plus allowing output and redistribution of content, all efficiently administrated for the open-source community.

However, each manual must be managed separately and that’s where technical writing and document content management skills shine.

Flossmanuals: A Help Authoring Tool Killer?

This bears examining because there’s a lot to be said about context-sensitive help within applications as well as the authoring platform for help. Tom Johnson’s recent poll and the ensuing HATT debate shows a passionate user base for tools.

Janet states:

Flossmanuals.net is heavily oriented towards book-style manuals; you could use it for topic-oriented online help, but it might be a stretch—a HAT it is not. But now that there is FLOSS Manuals, there simply is no longer a technological reason for any open source project not to have documentation.

I agree with this. There’s a method to the madness when you’re writing online help files and formatting is a critical element which a formal HAT tool is designed for.

For now, FLOSS is free*, with a minor amount of techie magic necessary. I envision beginning tech writers using this to support their early projects for open source software and quickly learning the basics of the technical communication trade.

*From the Flossmanuals site:

Our principle aim is not to be a publisher but to create as many tools and outlets for quality free documentation as possible. If that means you wish to use the FM tool set but host or ‘publish’ under your own banner, then that’s excellent. We are very happy to offer you a documentation platform to meet all your documentation needs.

Of course, all this is for free software / open source software projects only. If you create proprietary software then…

Clearly this means that you need to talk to them before boldly profiting from this community.

Workflow Focused Help Authoring Tools

Figuring out the fastest and best workflow is something the MadCap and Adobe teams are each wrangling, however they have markedly different approaches.

MadCap’s Team Server solution is in development. Along with the expected release of the publication centered form of Flare, Blaze, this is their collaborative workflow answer.  

Adobe seems to be several generations behind MadCap. Adobe’s answer to innovation seems to be to continue bundling new product lines into their Technical Communications Suite, plus to integrate what MadCap introduces as quickly as possible. If they can’t directly compete with innovation, bundling secondary products is another way to add value.

I can see that both are working towards collaboration tools - MadCap with X-Edit, Adobe with Acrobat and their newly acquired web-based collaborative tool, Buzzword.

My Opinion:

FLOSSManuals.net is a great place to start writing content for developers if you’re just starting out or would like to support a friend’s really cool application. I know of several for-profit companies that put out free widgets of one sort or another that don’t have tech writing staff. This would be perfect for that as well.

The other side of the coin is that it gives a good measure of what’s actually effective. While wiki implementation is challenging, on a cost scale when someone like FLOSSManuals is administrating it, it’s definitely worth exploring.

While not a HAT replacement, this model may work well to supplement a workflow.