Creating Content with Open Source Tools - Notes


Published on

The notes to a presentation I gave at DocTrain East 2008 on Open Source Tools for documentation

Published in: Technology, News & Politics
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Creating Content with Open Source Tools - Notes

  1. 1. Creating Quality Content with Open Source ToolsBy: Scott Nesbitt When you think of Open Source software, what comes immediately to mind? Probably Linux, and maybe applications like MySQL, PHP, Apache,, and Mozilla Firefox. Applications that have entered the popular consciousness, and others which can be described as the plumbing of the Internet. But Open Source is a whole lot more -- a wide range of utilities, applications, and tools. And a number of those tools are well-suited for creating quality content. This presentation will introduce you to the Open Source tools and techniques that you can use to create quality content -- everything from documentation, Web content, marketing material, collateral, or whatever your deliverable is. My goal isnt to convince you to throw away the software that youre using and adopt Open Source. If you want to do that, great. I just want to open you eyes and your minds to an under appreciated and under noticed alternative to commercial software for creating© 2008 Scott Nesbitt Creating Quality Content with Open Source Tools - 1
  2. 2. content. Around 1999, I learned basic XML and started thinking about using it to create documentation. InA word about terminology fact, as part of an XML course I was taking I wrote a report on how to use XML to create modularAs you may or may not know, there is a lot of documentation. Of course, I discovered a number ofcontention between the free software and Open Open Source tools for doing just that.Source software communities. Theyre similar, but Around that time, I read an article by a Toronto-basedthey arent the same. One of the main differences technical writer named Michael Skeet who wrotebetween the two is ideology. You can visit the Web about how he was using Open Source tools tosite of the Free Software Foundation to read more document the Open Source software that was beingabout this. developed by this then employer.For the purposes of this presentation, Im going to That article opened my eyes to a number ofuse the term Open Source to denote both free possibilities, which Im still exploring to this and Open Source software. I know thats notthe correct distinction to make, and that I should be As a consultant, Ive used various Open Source toolsusing terms like FOSS (Free and Open Source (some of the ones which are mentioned in thisSoftware) or FLOSS (Free/Libre and Open Source presentation) to create content for clients. I even hadSoftware). a hand in setting up a DocBook toolchain for one of those clients.But I like to keep things simple, and for the sake ofeuphony and to avoid acronym overload, Im usingthe term Open Source. Quality content The frustrated user. Thats someone technicalA little background communicators dont want to see or even hear about. Quality content avoids creating frustrated users. ItMy adventures with Open Source documentation helps the user effectively work with a product. Ittools started in the early to mid 90s. In my informs them about it.struggling, early freelance days did a lot of worktypesetting documents using TeX and LaTeX.© 2008 Scott Nesbitt Creating Quality Content with Open Source Tools - 2
  3. 3. Quality, believe it or not, means different things to Who uses this stuff, anyway?different people. One of the better definitions ofquality that Ive come across is from the firm that Im As you might expect, just about every Open Sourcedoing some consulting with now: quality is usefulness project uses Open Source tools to create content.- something high quality is fit for purpose. But its not just small projects. A number ofAs far as content goes that purpose, for me, is to commercial Open Source software vendors also relyinform and educate. on these tools to author and publish content -- not just documentation, either. Companies like:I wrap the concept of quality content in what I callthe five Cs: • Red Hat • MySQL • Clear • Call Genie • Concise • Amazon Web Services • Consistent • Novell (at least on the Linux side of the • Complete business) • Correct • CodeWeaversUsually, I talk about the five Cs in relation to And a number of others. The kinds of content beingdocumentation. But they apply to other content in an produced range from user and developer guides toenterprise, too -- everything from marketing system administration and installationcollateral to Web content to white papers. And Open documentation and online help, to whitepapers,Source tools are up to the job of creating that kind of reports, and Web content.content. Some of these firms use Open Source tools becauseThe five Cs have little to do with the software that they themselves develop Open Source use. More on this later. Eating their own dog food, if you will. Others do it because they want to deal with open formats and© 2008 Scott Nesbitt Creating Quality Content with Open Source Tools - 3
  4. 4. tools that they can fully customize. And most of those and for creating knowledge base articles. While Icompanies want to avoid vendor lock in. have some familiarity with such tools, Im not entirely comfortable talking about them.That said, a number of Open Source developmentshops dont use these tools. Like who? Here are a few Editorsexamples: You need to get your words down somehow. And, obviously, thats where an editor comes in. While • SugarCRM (FrameMaker) theres no Open Source equivalent (or even • Vyatta (FrameMaker) something close) to a tool like FrameMaker or Blaze • Knowledge Tree (Help and Manual) there are some strong and flexible editors out there. • CiviCRM (Confluence) A tool of choice among Open Source geeks,As for why, there are a variety of reasons. You can especially ones who work with XML, is the text about some of them in this article. I know what youre thinking: entering XML tags manually in a text editor is painful. In the extreme.The tools And youre right. But two editors, Emacs and JEdit, have excellent support for XML. A popular extensionWhich is what were here to talk about, isnt it? There to Emacs, called psgml-x, enables you to (fairly)are quite a few documentation tools in the Open easily enter tags and validate your documentsSource universe. Many, however, arent flexible or against a DTD.robust enough for the type of work that were doing. Eclipse, which can be described as an IDE for justThe tools that Ill be talking about are editors, about everything, can easily be extended to edit XMLdocument formats (OK, not a tool but ...), wikis, files -- including DocBook and DITA. The maincontent management systems, and tools for creating problem with Eclipse, though, is that its monolithic.and editing graphics. Eclipse can do just about everything but using it to write documentation seems to be overkill.Tools that Im not going to touch on are ones fordocumenting source code, for creating Web content, Which is where Vex comes in. Its basically a stripped-down version of Eclipse -- Vex has little of© 2008 Scott Nesbitt Creating Quality Content with Open Source Tools - 4
  5. 5. the overhead of its parent. Its a lot like an XML word are what I describe as lightweight: theyre easy toprocessor. It supports DITA and DocBook, along with use and their conversion tools use little in the way ofXHTML, and can also use a number of Eclipse plugins. system resources. However, most of the lightweight formats only output HTML and arent the best choiceIf these kinds of editors arent your thing, then for documentation.maybe you should give Writer a look.I know what youre thinking -- not another word There are a handful of application languages, though,processor! Well, Writer is that and a lot more. that are well suited for producing content in various formats.A few years back, journalist and technical writerBruce Byfield compared Writer and FrameMaker. Im sure youve heard of DocBook and DITA. YouYoud think that FrameMaker would have won hands might have used one or both of them, or are usingdown. Well, it wasnt that cut and dry a victory. them. The basic tools to transform DocBook and DITAByfield looked at seven key areas, and FrameMaker are Open Source, and the content files can be writtencame out ahead in only two. Writer came out on top and edited in many applications. Some of these toolsin two, and the rest were a tie. are good, but not great. More on this later.Writer does have some useful features for technical AurigaDoc was created in true Open Source fashion:communicators, including conditional text and to scratch a developers itch. This itch was to createmaster documents that actually work. And it derives an internal documentation system. Its an interestinga lot of flexibility from its extensions. Ill be talking format, which is a combination of XML and HTML andmore about a couple of these later. uses Cascading Stylesheets for formatting. The AurigaDoc engine outputs a number of formats,Document formats including HTML, four forms of online help, PDF, and Postscript. Its easy to use, and good for shorterI think thats a more accurate description than documents.markup languages. Many of these formats, and the AsciiDoc straddles the gap between lightweightsoftware used to produce end-user content from formats and DocBook and DITA. Its aimed at peoplethese formats, lie in the realm of Open Source. who write articles, reports, and short books. TheAnd there are a lot of them. Many of these languages source files are written using a wiki-like markup, then© 2008 Scott Nesbitt Creating Quality Content with Open Source Tools - 5
  6. 6. converted to higher-level markup like XHTML and tasks.DocBook XML. From there, you can convert Two problems that wiki users face, though, aredocuments to PDF. getting content into and out of a wiki. Sure, you canTheres a Web-based front end to AsciiDoc in the enter it directly or copy and paste content. But thatsworks. Its supposed to let you grab individual source not the most efficient way of doing things. But yourfiles, edit them, and combine those files for output. options are somewhat limited. There is, for example,Well have to wait and see. an Writer extension that enables you to craft content in Writer and then save it toRemember when I mentioned using Open Source MediaWiki. And, unfortunately, only to create documentation for a couple of clients?One of the formats I used was AsciiDoc. The client Most wikis allow you to export content as HTML, XML,had a very restrictive budget, and needed an HTML- or even RTF. But those formats still need somebased online help system for a Web application that tweaking to structure them. DokuWiki has an plugincould be easily maintained by someone with a that saves individual pages in OpenDocumentmodicum of technical knowledge. With AsciiDoc, I Format. If your wiki pages have been properlycreated the help topics and then output them to marked up, the plugin will translate that into actualHTML. A Perl script generated a table of contents and styles -- for example, Heading 1, Body Text, and thethen everything was wrapped in a frameset. I also like.put together a short guide to how to update the help A single tool for adding and exporting wiki content infor the client. a structured format doesnt exist. At least, not yet ...Wikis Content management systemsIts no secret that wikis are one of the more popular Not every shop uses a CMS for their content,topics among technical communicators. Theyre easy although many should. Open Source CMS are anto use, enable collaboration with other technical interesting mix. Alfresco, KnowlegeTree, and Epiwarecommunicators, with developers, and with aim to be the Open Source equivalents of big-namecustomers. Theyre also great for keeping track of applications like Documentum. The latter two arechanges to documentation and for a variety of other© 2008 Scott Nesbitt Creating Quality Content with Open Source Tools - 6
  7. 7. meant for smaller organizations, and probably like. Each application can save files in a variety ofcouldnt handle the volume of documents that some common graphics formats, including PNG and pubs teams produce. If a picture is worth a thousand words, then aWhile theyre actually source code control tools, screencast must be worth several thousand. WhileSubversion and CVS are regularly used by technical not quite on par with software like Captivate, you canpublications teams for content management. Theres use CamStudio and Wink to create screencasts, witheven an Writer extension that allows and without to connect to a Subversion repository and checkout files. The interesting thing about this extension is Help authoring applicationsthat it works with Linux and Mac OS, but not withWindows. This is one area in which Open Source falls flat. Once again, theres no Open Source equivalent toGraphics commercial tools like Flare, RoboHelp, and WebWorks Publisher. The tools that are out there areA picture is worth a thousand words. If nothing else, a more like help authoring IDEs. You type or paste yourwell-designed image can help clarify a concept or an content into an editor, and then generate youridea. There are a handful of solid Open Source output. Hardly single sourcing.applications for creating these kinds of images. The closest you get to single source help authoring isThe best-known Open Source graphics tool is with DocBook and DITA. They can generate JavaHelparguably The GIMP. Its an image editor, sort of like and Microsoft HTML Help. Theres also a DocBookPhotoshop or Paint Shop Pro. While its good for stylesheet for creating browser-based help. You canediting and modifying images (like screen captures), read more about it in an article that I wrote. Theits not so good for creating graphics like diagrams. problem with the latter is that you have very little control over the interface. You cant add search,Thats where tools like Dia, Inkscape, and Xara additional navigation, or other controls without a lotXtreme come in. Theyre vector drawing programs of effort.that enable you to create all kinds of diagrams -- likeflow charts, directory and network diagrams, and the Why arent there there more professional-level Open© 2008 Scott Nesbitt Creating Quality Content with Open Source Tools - 7
  8. 8. Source help authoring tools? Partly because they • Determine the audiencearent on the radar of many developers. And partly • Develop a documentation planbecause coding such a tool is hard. Its really hard, • Begin gathering information about the productand Open Source developers have other itches to • Write the first draftscratch. • Send the draft out for review • Incorporate reviewer comments into theThe workflow second draft • Edit the second draftIn most ways, the workflow of an Open Source • Finalize the documentationdocumentation project mirrors the one that you use. • Have the documentation localized andThere are a few exceptions, though. For example, the translateddocumentation for Xubuntu (a lightweight version of • Publish the documentationUbuntu, a flavour of Linux) and for the One LaptopPer Child project is written towards the end of the Sound familiar? It should.development cycle. But that doesnt mean that nodocumentation activities were going on before that. Adopting a hybrid solutionThere is a lot of preparation and planning involved,and the writers are (of course) following the Theres a perception that the Open Source anddevelopment of the products. commercial software worlds are two very different worlds, and that never the twain shall meet. In theMany Open Source documentation projects, even for real world, though, you sometimes have to becompanies like the ones listed earlier, are carried out pragmatic. That could mean creating a hybridby distributed teams. Writers in different parts of the toolchain of Open Source and proprietary or the world. And, some projects have thebenefit of a lot of eyes on the documentation. Why? Lets take a look at a few examples. ApacheWriters, developers, editors, QA, users. That helps FOP, which is used to transform XML to PDF andcatch problems. similar formats, is a good tool. But it doesnt support all of the XSLT standard. When you look at a PDFIn general, though, the Open Source documentation produced with FOP, youll notice widows and orphans,workflow is something like this:© 2008 Scott Nesbitt Creating Quality Content with Open Source Tools - 8
  9. 9. problems with tables, and some spacing problems. Going openThe DITA Open Toolkit does a decent job, but Idifficult to set up or customize. On top of that, both Now that you know a little more about Open Sourcetools cant handle larger volumes of documents. tools, its time to look at the big question: why go Open Source?With DocBook (which Im more familiar with thanDITA, I have to admit), you have at least two Open One attraction of Open Source software is its price.Source options for better print and PDF output. One is They are free, and they can be customized. Butdblatex, which creates PDFs by converting DocBook remember that there are costs involved. More on thisfiles to LaTeX and then typesetting them. And theres soon.docbook2odf, which is a script that converts DocBook These tools often use simple, standard, formats. Thefiles to OpenDocument Format (ODF) files. You can formats are unlikely to change significantly (andopen ODF files in Writer, apply a new wont become incompatible) in a few months ortemplate, and then export it to PDF. years. Theyre formats everyone in an organizationStill, these solutions dont come close to the quality can use -- no special software is needed to read oroutput and and the robustness of XEP or Antenna write them. Theres no vendor lock in.House, or if FrameMaker is used as the publishing The software and, more importantly, the idea behindengine. Open Source lend themselves to greaterOn top of that, you might want to use a more flexible collaboration. This collaboration could be within yourand robust editor than some of the ones that were organization, or with customers. A collaborativementioned earlier. oXygen XML Editor or XMLmind, relationship with customers is a good one to foster.for example, instead of Emacs or Vex. Why? Customers are using what youre documenting in ways that youve probably never considered. YouA number of companies, including ones that produce can improve your documentation by tapping into theand use Open Source software, use such hybrid experience of customers. Heres a bit of wisdom fromtoolchains. Novell, for example, outputs HTML the Apache Lucene project:versions of its Linux documentation using the OpenSource xsltproc but turns to XEP to generate the PDFversions of those documents.© 2008 Scott Nesbitt Creating Quality Content with Open Source Tools - 9
  10. 10. and be difficult to maintain. You just cant download a I think the standard Open Source mantra is applicable load of software off the Internet and expect them to here. Lucene, like most open source programs, is always work flawlessly out of the box (or the digital willing to accept patches, especially for documentation. equivalent of the box). If youre not prepared to, or Furthermore, there are many excellent tutorials, able, to do the maintenance and setup work then PowerPoints, examples available for the basics of maybe Open Source software isnt for you. Lucene, many of which are avaible via the Lucene Wiki. If your sole motivation for switching to Open SourceIf youre a techie, or want to be one, and dont mind is to save money then Id reconsider. A few yearsgetting your hands dirty setting up and maintaining ago, I worked for a company whose technicalthe toolchain then this is a good choice for you. publications department was, believe it or not, part of sales. We were expected to make money. Of course,When not to go Open Source the department didnt. To cut licensing and maintenance costs, they decided to roll their ownAre there any reasons for not adopting Open Source solution and deliver the documentation as Eclipsefor your documentation needs? Of course there are. Help. Management didnt think about the overheadHere are a few reasons for not going open. for the writers, for testing, for development, and for the users.Is your current set of tools and processes workingwell for you? If the answer is yes then theres no Migration strategiesreason to switch. Too many variables may creep in --like lost productivity to the cost of customizing XSL So, lets say youve decided to adopt Open Sourcestylesheets -- to justify that kind of move. software for your documentation needs. What willYou also need to consider the weaknesses of Open you need to do to migrate? Here are a few generalSource tools when youre deciding on whether or not make the move in that direction. Theres no one First, consider the documentation that you currentlytool to rule them all. Youll need to roll you own have and how easy or difficult it will be to migrate ittoolchain from a set of disparate applications and to an open format. It will probably involve more thanformats. That can take a lot of time, a lot of work, just saving it in a different format and then© 2008 Scott Nesbitt Creating Quality Content with Open Source Tools - 10
  11. 11. processing it with Open Source tools. the documentation, hiring a consultant to customize your XSLT, templates, and the like.Next, research the tools. In depth. Read, download,test, and then test some more. Repeat this as often You should also think about the time that it will takeas it takes. to get the tools up and running, and for the technical writers to learn how to effectively use those tools. IfConsider the pros and cons of both a purely Open youre moving from proprietary formats to open ones,Source and a hybrid toolchain. factor in the time that will be required to convertPerform the migration in small steps. Look at it as if your existing documentation to the new format. Youyoure inoculating yourself against snake venom. wont be very productive in that time.Start off slowly, with small doses of venom to build Unfortunately, there arent any studies or reports onup your resistance. Take a relatively simple the cost savings related to moving to Open Sourcedocument and convert it. Note the problems and the documentation tools. At least, none that I can find.pain points, and then document them. Repeat the Any initial savings wont be that great, unless youreprocess, using what youve learned, with the other working with a huge team. You wont be hiring a newdocumentation and content in your organization. writer with those savings, at any rate.Assessing the total cost of ownership I think that the true measure of TCO comes over the space of several years. In the short term, a tech pubsNo discussion about Open Source tools is complete team will pick up the new tools and processes. In thewithout talking about total cost of ownership. Yes. longer term, your costs for licensing and productTCO. Three little letters, but ones which seem to maintenance will drop. With any luck, the morestrike fear into the hearts of managers and workers technically curious on your team will be able toeverywhere. While Open Source tools are ostensibly provide, there are costs involved.What kinds of costs? The tools are free unless, of The tool is not importantcourse, you decide to go with a hybrid workflow. But At least, its not always the most important may need to pay for things like training, a server Lets face it: the tools are a convenience for us. Thethat the tech pubs group uses to publish and archive© 2008 Scott Nesbitt Creating Quality Content with Open Source Tools - 11
  12. 12. folks reading the documentation that we produce In the end, though, you can have Open Sourcedont care if it was done in FrameMaker, with software. You can have proprietary software. You canDocBook or DITA. They dont care about single have a combination of both. The choice is yours.sourcing, topic-based authoring, or anything like that.Its not to say that those arent important. They are,but only to us.The people who read documentation want and needmaterial that conforms to the five Cs that Imentioned at the beginning of this presentation.One of the best pieces of advice on tools that Iveread is this: [T]o get the most from an XML workflow, it must be seen as much more than just a tool or a technology: there are serious organizational and cultural issues that are in many ways even more challenging than the technology itself.That advice applies to choosing Open Sourcesoftware, too.Before you decide on your tools, you mustunderstand your needs and the needs of your users.You just might have to rub your crystal ball a bit andtry to envision how all those needs may grow. Assomeone said, the tools arent the train. Theyre thecaboose.© 2008 Scott Nesbitt Creating Quality Content with Open Source Tools - 12
  13. 13. Contact MeWeb site:http://scottnesbitt.netEmail:scott@scottnesbitt.netBlog:© 2008 Scott Nesbitt Creating Quality Content with Open Source Tools - 13