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.

Continuing from eDMS Roshambo Part 4 | Feedback with the wiki versus the MadPak with Feedback Service.

Wikis clobber eDMS when it comes to collaboration. Wikis are great but getting the end result into a user manual format still requires an external tool.

Rock Paper Scissors (RoShamBo): Wiki vs the MadPak, Analyzer, and Feedback Service

There are strengths to not having a Wiki model introduced right away into a corporation. Dan Ortega mentions corporate policy holding back the anarchy, however it helps considerably when there is a gradual move towards the Wiki model. 

MadCap is halfway through the Wiki model already with just the MadPak. Add to that the Analyzer and Feedback Server/Service’s Web 2.0 features, you’ve got yourself a good step past Wiki as far as maintaining positive control over the content.

With Analyzer you’re looking at a Documentation Manager’s dream package.

I think the key element is… how much time would this all save each role a Technical Communicator has. Let alone the workflow’s editing search and correction time.

Cost – $1200 for the MadPak and $400/quarter for the Feedback Service ($1600/year) so you don’t even need to host a server and stress the IIS configuration. No pricing on Analyzer is yet available. I really should get some sort of Amazon Buy-now button for this stuff.

As far as the industry tools are currently set, MadCap Analyzer could save upwards of $50k – $80k a year in tech writer time and other software. That’s pretty hefty, although at the time I’m writing this MadCap hasn’t set a price for the Analyzer.

Note: Pricing for Analyzer is pretty cheap, as I edit this article I find that it’s only about $200 or so to upgrade.

Updating Any Content Effectively Requires Feedback Data

Wiki strength is that anyone can provide feedback or edit content. The passive feedback of viewed pages falls under another product’s reporting (AWStats or WebTrends to name a couple).

Let’s examine the potential benefits that usage statistics and feedback could make to eDMS and/or wiki content. The two we’ll look at are Adobe RoboServer and MadCap’s Feedback Server.

Both provide feedback about page usage and search terms. This allows content creators and technical writers to evaluate which areas to focus their attention on, sort of like a triage, but MadCap’s goes a step or two farther and adds a Web 2.0 aspect with the addition of Comments pages within the web interface.

Understanding the origins of the RoboServer and Feedback Server comes in handy when comparing their technologies.

History Lesson: From DynaHelp to RoboEngine to RoboServer & Feedback Server

Eight years ago the current RoboServer was known as Dynahelp. The RoboHelp Enterprise component RoboEngine was derived from DynaHelp, a Blue Sky Software (BSS) / eHelp product that launched in 2000. Dynahelp was used by companies such as American Airlines and was an enterprise solution.

From destinationCRM’s July 2000 article DynaHelp’s Smart Web-Site Improvement Tool:

DynaHelp, [is] a server-based help tool that not only steers users through a site, gently assisting them when they become stuck or confused, but also gathers data on particularly troublesome interface and usability problems and reports the problems back to webmasters.

DynaHelp’s database makes a record of every user request for assistance and sends reports on these problematic areas back to the webmaster, explains Steven Jacobs, a Web-site designer and consultant on usable design. ”

A DynaHelp site gets more usable the more the site is used,” said Jacobs. “But you don’t have to frustrate your customers to find out how not to frustrate them.

DynaHelp was, as I understood the BSS corporate history, one of the main reasons that BSS changed its name to eHelp right around the time of the dotcom/dot-bomb in 2000. In late 2001 eHelp restructured and returned leadership back to Jorgen Lien, the founder after the core DynaHelp project failed during the dotbomb era. I could be wrong about the dates, it was before my time.

Jorgen brought eHelp back to the basics it made money on, and the core DynaHelp technology was adapted into RoboEngine, part of which was sold as the RoboInfo Server, a Policy and Procedure eDMS powerhouse at a market disrupting price point.

RoboInfo Server allowed users to index all their existing documentation, use the RoboHelp GUI and develop intranets with searchable linked content. All this for only a couple thousand dollars made it attractive.

History lesson: Competitive workflow five to seven years ago

RoboServer’s full purpose seven years ago (2001) when they introduced it was to make that existing content searchable. It was a $20,000 search engine that did natural language search (NLS) all packaged and sold for $2000.

That was disruptive on its own two legs, but add to it the online help and reporting, and it got better and better. But now it’s old.

According to Vivek Jain, Group Product Manager, RoboServer’s innovation apparently is in fixing its bugs (See Vivek’s Quality IS Innovation post on Adobe’s TechComm blog) however even that’s not compelling with the botched and blurry Captivate import into RoboHelp. Not to mention the quality of the product’s online help.

RoboHelp X4(?) and X5 (2003) made PDF import along with .doc file import possible so you could repurpose existing archived content. You could get a license for those for about $1000.

You can still get a license for X5 for around $350. OR you can buy the Adobe TechCommSuite for something under $800.

Those solutions will keep you at the same workflow competitive to Wiki. Versus desktop applications and a black hole of an intranet, you’re much better off. But it’s old. It’s not hip, with it, and let’s face it, the ‘innovation’ of RoboServer has been in trying to keep it running through the new Microsoft incarnations of NT server technology and their updates.

Or… Like in Star Wars, now experience the TRUE Power of the Dark Side

Here we are in 2008. It’s a far cry from 2000 and the launch of DynaHelp.

I’m betting on this year’s killer app for workflow being MadCap’s Flare 3.0 equipped with Analyzer and the Feedback Server, which I reviewed a few months ago. So we’ll look at the Magic Box being either Flare or Blaze.

Now, the real power of a true Collaborative Workflow with various forms of content would be:

First, that the Subject Matter Experts could use the tool of their choice, (FrameMaker, Word, etc.) and update the content at any time regardless of where it sits,

…and your magic box would then, on a cron set (for apache users), or IIS script set command line interface (CLI) schedule update your content automatically,

…leaving the Technical Communicator free to do her/his real job; concentrate on structure and form rather than the nuts and bolts behind the structure and form.

It gets better, not only can you search, but with Feedback you’re able to get the results you want passively; you can see what search terms people are using.

The Wiki without wiki anarchy: Feedback’s Comments.

Each topic has the ability to maintain those Comments and the Technical Communicator can see comments as they happen. Which means they can do updates… real time.

Output and feedback options are available both inside and outside the firewall.

See my podcast with Mike Hamilton, MadCap VP for specific details about his recommended workflows and Mike states that he doesn’t rule out a wiki model in the future. He also gives good 411 about what you can do today with his products while minimizing the anarchy that a wiki could become.

And with the Analyzer, bringing all that disparate content under control (content wrangling, as one blogger calls it) is made super simple and cost efficient because you can match up your similar phrases and frequently used terms and homogenize the entire project.

When it comes to refining a Knowledge Management workflow, I’ve been researching into collaboration tool adoption. I tend to look towards the internet for what the free market economy brings up.

There’s a sweet spot between the user familiarity of an email and the openness and collaboration capabilities of a wiki; I tend to use a DevBlog instead. DevBlogs, or development-based blogging, has an adoption rate of about 60% of my client base and allow remote collaboration and concept review.

Hence the DevBlog concept, and my adoption of the WordPress standard for Blogging. Most people can use the web-based Comments area because they have already adopted the technology by viewing or interacting on other people’s blogs.

I believe this is because of the subject structure, and most importantly, the ability to collate the information by relativism; nesting a family of knowledge within Workflow Collaboration such as this post falls into, allows me to communicate effectively with each part of my team since everyone knows where the related posts are.

Knowledge management could use wikis as a dream tool, however repurposing the content tends to be cumbersome. I expect that the Web 2.0 focus of MadCap Software’s Flare v3.0 addresses this issue nicely.

So the question comes down to whether there a better free tool – in this case a wiki – that can provide what the corporation needs to collaborate and collate information effectively?

Corporate Wikis – Ready For Prime Time?

I’m torn on the issue of wiki usage within a company. Rivalry remains the top killer of corporate thought, IMHO.

I think it depends a lot on the type of corporate structure; to be blunt about it a hostile work environment rewards innovative and individual thought destructively and can jeopardize someone’s position. Having a wiki, which tracks good ideas openly, may endanger those free-thinking people without them even realizing it.

If the company is based on collaboration from the get-go, wikis would be enormously effective. Learning / Training departments who use a departmental approach might be able to gain incredibly from the ability to change information as it is gathered from the instructors in the field, however email may work just as well.

Flare, with the Feedback Server, allows two-way interaction which is recommended for use within the secure firewall, in the form of a ‘beta’ site during product development.

[Flare 3.0 and the Feedback Server have] Web 2.0 community capabilities, allowing readers to add their own comments and provide feedback on your documentation… …providing the ability to allow readers to rank the quality of the topics and content using a simple star system. — MadCap Software

The ‘beta’ site then has the help file with open comments allowed by the Subject Matter Experts (SMEs) and the Product Managers (PMs) can determine what content they want included in their deliverable for the product release. Related topics are managed using ‘See Also’ or A-links which update relatively to the content placement. Add to that the simple methods of including and excluding content based on the Conditional Tags (Build Tags for RoboHelp users) and you’re laughing.

The final product is either a self-hosted help file, or a web-based help file that has had many more eyes on it and has had more input through comments by the SMEs than was earlier available with just a hardshelled help file and email.

All in all, I think wikis are a technology to track, but for most knowledge management and software help authoring, I would recommend spending the up-front money on the Flare/Feedback combination. That way the content can be provided in Word, XML, HTML, or PDFs and assembled by a professional Technical Communicator.

Wikis in Game Development

One exception to this would be within the world of Game Development. Having a multiple author environment is critical for ‘blue-sky’ thinking in game development, and refining the game concepts down into brainstorming requires documentation. Because the concepts have to flow freely, the initial phase is very important not to stifle. Creativity which is then recorded is critical.

When it comes to the narrower and more defined area of taking those ideas and placing them into the requirements documentation, having something in an XML framework makes life easier also.

Wikis in Pinstripes – Wikipedias In Corporations

Here’s a great article I’ve discovered about wikis in business, found on the Harvard Business School ‘Working Knowledge’ site. My experience with Harvard MBAs has not left me impressed but this is a very well reading article, with a great question and answer session at the end. Quoted from http://hbswk.hbs.edu/item/5605.html :

Harvard Business School professor Andy McAfee has his doubts that a corporate encyclopedia would have much value. But the underlying wiki technology—basically an electronic document and repository where participants can throw out ideas, comment on the work of others, and share documents—has more promise.

HBS Cases: How Wikipedia Works (or Doesn’t) — HBS Working Knowledge

What Wikipedia has shown is that self-selection is critical. Peer review is critical. So there is a challenge for firms that are used to managing employees and allocating the resources in a very top-down kind of way. Now we have a technology that enables self-selection, transparency, openness—how does a manager or management deal with the technology? Do they implement it in a way that’s true to the spirit, or is it top-down? And, again, there are some very successful examples and some not so successful examples.

Some people wonder about collaboration and how effective this form of communication is – are wikis just a fad, or are they the focus on the future?

The new generation of students, the MySpace and Facebook generation, will be hitting the HBS campus soon; they are already here to some degree. They are so used to collaboration and sharing in a distributed fashion, for instance, going to a friend’s page and leaving a note. They have these asynchronous ways of coordinating and collaborating.

Q: If you were to counsel companies that need more cross-collaboration and need to break down silos, what technologies would you recommend?

What I usually tell companies is, “Look, if you want to activate this Web 2.0-style energy inside your company, management is going to make all the difference. And if you manage it the old-fashioned way, or if you don’t manage it and you just have the if-we-build-it-they-will-come philosophy, you’re probably going to be disappointed.”

You need to be actively involved—I’m going to fall back on buzzwords—in coaching to get desired behaviors and leading by example, and not shooting people when they step a little bit out of line. The organization is going to be watching what happens, and you’re going to send very, very strong signals one way or another that are going to be picked up very quickly.

Corporate Wiki Success Depends On Leadership

Even with the right tools, successful corporate communication comes down inevitably to quality leadership.

All in all, I think wikis are a technology to track, but for most knowledge management and software help authoring, I still would recommend spending the up-front money on the Flare/Feedback combination.

That way the content can be provided in Word, and assembled by a professional Technical Communicator, and with a limited ability to speak too much out of turn, it should keep anyone from sticking their foot in their mouth in print in front of the Executive team.

wiki,Game Development,DevBlog,Web 2.0,Enterprise 2.0,wikipedia,corporate blog,technical communication,technical writing,technology adoption,project management,workflow,collaboration