• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Think Outside the Book - Notes

Think Outside the Book - Notes



Notes for a presentation I gave at Toronto Wiki Tuesdays on using a wiki to write and deliver documentation.

Notes for a presentation I gave at Toronto Wiki Tuesdays on using a wiki to write and deliver documentation.



Total Views
Views on SlideShare
Embed Views



0 Embeds 0

No embeds



Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
Post Comment
Edit your comment

    Think Outside the Book - Notes Think Outside the Book - Notes Presentation Transcript

    • Thinking Outside the Book:Wikis for Writing and Delivering DocumentationBy: Scott Nesbitt Documentation. Its a necessary evil in a software or hardware project. In some ways, peoples attitude towards documentation can be distinctly bipolar. There are people who read and use documentation. There are people who dont believe its necessary. There are those who never (or claim to never) read it. And there are those, like me, who write it for a living. Whats funny is that all four camps complain when theres no documentation, or the documentation is sub par. Broken glass. Thats how I look at the ways in which documentation gets delivered. Some companies still put out printed, dead trees manuals. Most companies, though, issue PDFs or HTML-based documents. Theres also online help (you know, what you get when you press F1). Word documents. Text files. UNIX man pages. Forums. Knowledge base articles. Files on hard drives. In emails and in places like Sharepoint repositories and Lotus Notes databases. For the most part, theyre good formats. But theyre mired in a sometimes unnecessary level of complexity. On top of that, updates to the documentation often cant be made and deployed quickly.© 2009 Scott Nesbitt Thinking Outside the Book - 1
    • Each shard of broken glass represents documentation in a project. More on FLOSS Manuals in a little while. Adamdifferent format. Its a form of information chaos. mentioned that he noticed there is a lot of tool fetishism in the technical writing world. And hes correct.Enter the wiki I could probably spend 10 or 20 minutes talking about all theIn many cases, a wiki can bring order (or something tools of the tech writing trade, and just as long about theresembling it) to that chaos. A wiki gives technical writer a various formats in which documentation is delivered. Thatway to centralize documentation in a single location. A wiki kind of talk is only interesting to technical writers themselves.gives subject matter experts access to it. A wiki offers a very But you know what? A wiki can be an effective substitute forflexible environment for creating and delivering many of those tools.documentation, and for enabling users to contribute content. So, what are the advantages of using a wiki forFor the next 50 minutes or so, Ill be discussing how people documentation?in the wacky world of technical writing are using wikis. Illlook at the tools, the techniques, the advantages, and the ● You can quickly set up a wikidrawbacks of using a wiki for creating and deliveringdocumentation. ● Its easy to use and editWhats interesting is that what Im going to touch on in this ● A wiki can promote and enable rapid authoring,presentation applies to any content that you put on to a wiki. updating, and publishingYou dont need to be a technical writer to take advantage ofwhat Im going to talk about. ● It can enable collaboration, both with people in a development shop and outside itWhy a wiki for documentation? ● A wiki has built-in version control and change tracking – this can be essential when you need to recoverWhen technical writers get together, one of the things that contentthey invariably discuss (and argue about) is tools. Last year,I talked to Adam Hyde who founded the FLOSS Manuals ● It acts as a central repository for documentation (and© 2009 Scott Nesbitt Thinking Outside the Book - 2
    • other information) inside and outside an enterprise. ● A number of Open Source projects (small and large) You dont need to implement a costly and complex like Apache, Ubuntu, the Fedora Project, and content management system OpenOffice.org ● Sun Microsystems ● With a wiki, you can take advantage of any number of so-called Web 2.0 features like RSS, tagging, and ● Motorola searching using both the built-in search engine (OK, ● Splunk not so Web 2.0) or with a tag cloud ● Adobe LabsWikis are very popular in shops that use the Agile ● WebWorksdevelopment methodology. Because of the short iterations(one to two weeks) used by Agile teams, its easier to post ● Atlassiandocumentation on a wiki for review rather than passing paper ● United States Armyor electronic copies (along with the attendant problems thatcauses) to subject matter experts. All reviewing and ● Various Internet Service Providerspublishing (maybe even the writing, too) is done on the wiki. Thats just a few customer-facing wikis. What would beThe documentation keep up with development, instead of interesting to find out is the number of firms and projects thathaving to scramble to catch up at the end of a project. are using a wiki behind a firewall. I looked around, but couldnt find any figures about that. Im sure, though, thatHeres an interesting statistic: according to wiki consultant number will be quite high.Stewart Mader, 39% of all wiki content in a companyconsists of documentation. Thirty nine percent. Thats a lot. How are they using wikis?Why not leverage that even further? It runs the gamut of documentation. Everything from userWhos using wikis for documentation? guides to operational and troubleshooting documentation. From API references to to user interface specifications.It might be easier to ask who isnt using them ... Heres a Some companies, like Atlassian (developers of the popularsampling of who is: Confluence wiki), use wikis to deliver online help.© 2009 Scott Nesbitt Thinking Outside the Book - 3
    • Atlassian publishes all of its documentation on a public wiki, difficult to navigate and to find information. And who wants topowered by Confluence of course. But Atlassian is goes one scroll through page after page after page reading long blocksstep further with their developer tools called FishEye and of text?Crucible. The documentation team has included icons in the In the context of a wiki, I look at structured content as beinguser interfaces of those applications. Click an icon, and broken into manageable chunks. Effective documentation isyoure taken to the appropriate documentation page on the a structured collection of those chunks, and not just a bigAtlassian wiki. And its not just a single icon in the UI, either. slab of information thats dropped in front of a reader.The help is relatively context sensitive, with help iconsbeside elements on a screen. For documentation, you can create that structure using the principles of topic-based writing. With topic-based writing,Minimalistic documentation and wikis each portion of a document – reference material, a procedure – is an individual bundle of information. ThoseIm a believer in minimalism in documentation. By that, I bundles are called topics. A topic stands alone; it doesnt relymean the documentation should explain how to do on any of the content that comes before or after it.something; all background and reference material should beelsewhere. If youre using a wiki, you can include that This approach results in what seems to be disjointedinformation elsewhere – out of the main flow of the documentation. Theres little, if any, continuity betweendocumentation. topics. Then again, who reads a manual from end to end?If youre not using a wiki as the primary delivery method for The benefits of this approachyour documentation, you can still take advantage of one byshunting all of the overview and background information to You might be able to see where Im going with this. Each wikithe wiki. If readers want it, they can get access to it with a page in a manual can be a topic. You can add continuity byclick or two. linking between topics. Readers can find what they need, either through cross references or direct linking.Structure This opens the door to have several possibilities. Like what? Here are a few examples:Structure is essential when putting documentation on a wiki. Online help. Each topic can be a a help screen for anJust dumping documentation – or any other content – on a application. You might recall that I discussed how Atlassianwiki doesnt do the content or the reader any favours. Its does this a few paragraphs ago.© 2009 Scott Nesbitt Thinking Outside the Book - 4
    • Reusing content. Thats another reason technical writers friend.like topic-based writing. Often in a manual or set of manuals With a namespace, you can have individual silos on the wikitheres content thats duplicated – warnings, tables that for each project and never their twains shall meet. Unless, ofcontain descriptions of log files or directories, that sort of course, you do some linking.thing. Imagine you have something like that across fourdocuments. Imagine having to change that four times with The namespace enables you to silo documentation intoeach new release of the documents? By using an include different categories – like user guides, references, oryou only need to do that once and the change is spread to all troubleshooting. This makes the documentation easier tothe affected points. An include is like a macro. It points to manage.content elsewhere on a wiki and pulls that content into aparticular page. Getting documentation into a wikiCustom documentation. Not everyone needs the sameinformation. Why should they have to spend time searching How youll do this will depend on whether youre startingfor what they need when they (or the technical writer) can fresh or moving your existing documentation to a wiki. Imbuild a custom document? That can be done in a wiki, and Ill assuming that you want to, as a friend of mine says, wikifybe giving an example later. your documentation. I wont go into the reasons why you wouldnt want to do that.Or, if the wiki supports the downloading of topics asindividual files, readers can collect the topics that are The most obvious way is to use the wiki itself. Every wiki hasrelevant to them in a format like ODT. Then, they can stitch at least two editors – one in which you use wiki markup, andthose files together in a word processor or other application, a WYSIWYG editor. WYSIWYG editors are a mixed batch –and print the resulting file or generate a PDF. some are decent, and some are really buggy. You could start off by writing documentation in a wordThe namespace is your friend processor, like OpenOffice.org Writer or Microsoft Word, and then convert it to wiki markup. You could do the same thingA namespace is like a directory on a PC or a server. Its with HTML. There are tools to convert between wordused to group wiki pages that contain similar content. If processor formats and wiki markup – like an add-on foryoure dealing with multiple products or even just multiple OpenOffice.org Writer, or the Word2Twiki macro. There aredocuments for a single product, then the namespace is your even a few HTML to wiki converters. Going this route,© 2009 Scott Nesbitt Thinking Outside the Book - 5
    • though, involves a lot of copying and pasting. On top of that, reports that Ive been reading, and from a few people Ivethere might not be a converter available for the wiki youre talked to, the results range from pretty good to ... well, not sousing. much.There are also bits of software called connectors, which That said, I have to give WebWorks credit. The companyliterally connect a word processor directly to a wiki. You write eats its own dog food – theyve wikified their documentationyour documentation, click a button, and its published to the set, which is available at docs.webworks.com.wiki. A couple of example of these are the Sun WikiPublisher for OpenOffice.org Writer, and the connectors RoboHelp2Wikibetween Confluence and Writer or Word. RoboHelp is a venerable application for creating online help.To be honest, these arent the greatest or even the most Again, its one of those applications that I have a like/dislikeflexible ways of getting the job done. They work, but many relationship with. A number of other technical writers are oftechnical writers (and Im talking about the tool fetishists I the same mind.mentioned earlier) would blanch at doing this. Still, RoboHelp is popular and thanks to RoboHelp2Wiki, youThere are ways in which to use familiar tools to write and can publish a RoboHelp project to MediaWiki. The processmaintain documentation, and then publish the content to a isnt as well automated as WebWorks solution; theres stillwiki. some manual fiddling that you have to do. But it doesnt do too bad a job from what Ive seen and heard.WebWorks PublisherI have something of a like/dislike relationship with WebWorks DITAPublisher. Its an application that takes files created in DITA is short of the Darwin Information Typing Architecture.Microsoft Word or Adobe FrameMaker and converts them to DITA is an an XML-based method for writing and deliveringonline help. Recently, the application gained the ability to information in a variety of forms. Remember when I waspublish directly to a wiki. Right now, the wikis that are talking about topic-based writing earlier? Well, DITA issupported are MoinMoin, MediaWiki, and Confluence. designed around those principles. With DITA, you buildI havent worked too extensively with WebWorks wiki topics and, from there, can build custom output by combiningpublishing function. I dont work with any of the supported those topics using something called a topic map (which iswikis, and a license for the software is expensive. From like a table of contents).© 2009 Scott Nesbitt Thinking Outside the Book - 6
    • Because of that, DITA is gaining a lot of traction in the breaking the documentation down into more manageabletechnical writing world. And since its topic based, DITA and chunks, rewriting it to make it shorter and more friendly fora wiki are a good match. the Web.One way to go from DITA to a wiki is with DITA2Wiki. Its anOpen Source tool from Lombardi Software that publishes a Getting documentation out of a wikiDITA project to Confluence. Not only do you get yourcontent, but also working navigation. I saw a demonstration Ive met a few technical writers who view a wiki as a blackof DITA2Wiki at a conference in 2008 and not only did it hole. They say its easy to get content into a wiki but tough towork quite well, it was fast. get it out. If not as tough as facing a black hole, then like pulling out a stubborn nail. Usually, I have to slap them downIs it that easy? when they say that in my presence. Its not entirely true.No. Its not enough to say Weve got documentation. Lets My view on this is dont worry about it. Why? The wiki is thedump it all on a wiki. You need to consider a number of delivery method. If you’re putting your documentation on afactors: wiki, you’re doing it for a reason. And that reason is to easily write, manage, maintain, and deliver documentation. It’s • What are the relationships between the various bits where customers will read and perhaps comment on the of documentation that you have? documentation. It’s where they’ll be sent when they press F1 • How do they fit together? or click the Help link in an application. It might even be where they find supplementary information like knowledge base • How can you link them? articles and introductory material. • What kind of feedback mechanisms will you have in That said, there are still a number of people who cant place? separate themselves from the idea of a PDF or a pile of • Will you have comment forms on each topic page? paper. For them, thats what a document is; not a page on a RSS feeds for new comments and updates to the wiki somewhere. Yes, the paperless office is still a myth and documentation? Email feedback? probably will be for a while.You might also need to restructure your documentation to Going back to the black hole comment, most wikis have themake it more suitable for a wiki. Simply shoveling what you ability to (either built-in or via add-ons) export to formats like:have on to a wiki might not work. Restructuring it could mean© 2009 Scott Nesbitt Thinking Outside the Book - 7
    • ● PDF said about topic-based writing? Thats pretty much how the contributors approach the sections of a book. Each topic can ● HTML stand alone. Which can make one of the ways of getting ● LaTeX content out of the FLOSS Manuals wiki really useful for the reader. ● DITA FLOSS Manuals makes getting content out of the wiki very ● DocBook easy. You can download an entire manual as a PDF , as a ● Some other form of XML set of HTML files, or you can get a widget that you can embed on a Web page or blog. ● LaTeX FLOSS Manuals also holds regular book sprints. These are ● ODT events held over two to five days in which a group ofThey can generate files in those formats either from a single contributors get together, both in one location and virtually.wiki page or from the entire document. Its not always the During the course of a sprint, the contributors literally write aprettiest output, but it works. book. Pretty much from scratch. At the end of it all, they generate a PDF and upload it to a print-on-demand serviceFLOSS Manuals called Lulu.com. You can download a PDF of the published book for free, or buy a dead-trees version.One very interesting wiki-based documentation project is But theres one more, very interesting way that you can pullFLOSS Manuals. FLOSS is short for Free/Libre Open content out of FLOSS Manuals. Its called Remix. Earlier, ISource Software. The goal of the FLOSS Manuals project is talked about giving readers the ability to pick, choose, andsimple: create quality free documentation for free software. publish what they want. Remix lets you do just that. Ive put together a short screencast that shows how it works.The project uses a heavily-customized installation of Twiki. Infact, its so heavily customized that you dont know youre While you might not get as many output formats as youworking in a wiki unless you take a really close look at page might with one of the so-called standard documentationtitles and the navigation between topics. tools, the FLOSS Manuals wiki does a lot of what software costing hundreds, if not thousands of dollars, can.On the writing side, theres no wiki markup involved —FLOSS Manuals uses a WYSIWYG editor. Remember what I© 2009 Scott Nesbitt Thinking Outside the Book - 8
    • Working with the crowd That more or less meshes with the figure I keep hearing bandied about: less than 10% (obviously far less) of users will contribute, and even fewer will continually contribute.This can be a tricky subject. There are a number of technicalwriters who are, to put it bluntly, control freaks. They dont How to get people to contribute is the social media question.like other people touching their documentation. When I run Theres no definitive answer. If you want more informationinto technical writers who think like that, I have to remind and ideas, you should definitely check out the followingthem that the documentation isnt ours. Its for the books:customers. Were only maintaining it. We have no rights of ● The Economies of Online Collaboration, by Peterpossession. KollackWhen we consider the crowd, we think about a specific mass ● Conversation and Community: The Social Web forof people who use the software and hardware that we Documentation, by Anne Gentledocument every day. They push it, bend it, and try to breakit. They use it in ways that we never imagine in our little ● The Art of Community, by Jono Bacondevelopment silos. And those people often have great tips Assuming that you do get people to contribute, you need toand techniques that we can incorporate into our 1) have a wiki style guide, and 2) ensure that contributorsdocumentation. So why not let the users, whose insights into follow it. If they dont, your structure will break down and theusing an application or device can be as valid as ours, have wiki will grow uncontrollably.a say too?A wiki has the potential to exploit those insights and that A shift for technical writersexperience by getting users to contribute new documentationand to add to whats there already. But this isnt easy to do. If Its not just a matter of adopting a new tool. Its a shift inyou build and open the wiki, they wont necessarily come. thinking and in doing as well. To effectively use a wiki,Going back to Atlassian, earlier this year the company technical writers need to:opened its wiki-based documentation to customers. I talked ● Keep structure first and foremost in their mindswith one of the writers there, and she told me that only abouta dozen or so people created accounts and started editing. ● Adopt topic-based writingThat number has probably increased a bit since then, but ● Re-evaluate how documentation is delivereddefinitely not exponentially.© 2009 Scott Nesbitt Thinking Outside the Book - 9
    • ● Seriously consider working with the crowd the look and feel of your corporate Web site or the online documentation that the company has produced in the past. A ● Give up any ingrained notions of control or good example of this, though not from the documentation proprietary interest in the documentation world, is the official wiki for the TV series Glee. That wikiIts not going to be an easy shift. looks, more or less, like the rest of the Fox Web site and not like a wiki.Keys to success But the real key to creating a successful wiki for documentation is content. Giving people the information thatThere are several of them. First off, once again, is the need they want in the way they need it. The documentation shouldfor structure. To create a structure and to maintain it. That focus on how to do things. If the content doesnt follow what Ican be tough, and will probably require one or more wiki call the 5 Cs:gardeners to do the job. ● ClearNext, youll need a way to baseline the documentation for ● Conciseeach release. Documentation changes, and if your employerfollows ISO or ISO-like processes, then during a quality audit ● Consistentyou may need to correlate the information that’s on a wiki ● Completewith a particular release of a product. Or, you might besubject to some regulatory requirements and need to ● Correctmaintain the digital equivalent of a paper trail. There are then its worthless, no matter how you write or deliver it.several ways to do that, like: • Putting the baseline version in its own namespace Is a wiki for everything? and locking it down • Taking a snapshot of the baseline version Definitely not. I dont mean to end this on a downer, but wikis arent suitable for every documentation task. Like what? • Exporting the baseline version to a different format Here are a few examples: like PDF When readers are behind a very restrictive firewall, thenYoull also have to make the wiki attractive to users. It having your documentation on a wiki has the potential toshouldnt look like a wiki. It should have something akin to© 2009 Scott Nesbitt Thinking Outside the Book - 10
    • shut them out. It all depends on how restrictive the firewall is, Summing upand how willing management is to ease those restrictions (atleast as far as the documentation goes). Wikis are very flexible and powerful tools for delivering anyDocumentation for mobile devices like smartphones poses kind of information. Theyre especially good for the creationan interesting problem. You have a small screen, and even and delivery of documentation of all kinds. Wikis can matchthe most minimalist skin for a wiki can be a bit cluttered. You many of the features found in the software commonly usedmight be able to make the wiki mobile friendly, but if readers by technical writers, software that can cost hundreds toneed to scroll through more than a couple or pages, or need thousands of dollars.to jump around a lot, they might not find the extra effort On top of that, the role of the technical writer is rapidlyworth it. changing. Theres more and more documentation beingTechnicians who work in the field might not have network or created by the people using the products that technicalwireless access to the Internet, and will be cut off from any writers document. By collaborating with users, and evenwiki-based documentation. On top of that, they might not having them write a portion of the documentation, technicalhave room to put down a laptop or a tablet. writers can produce documentation that is truly focused onLarger pieces of hardware, like copiers or medical the needs of the user. And a wiki is the perfect vehicle withequipment, also pose special problems. Its not acceptable which to do that.for people to have to run back to their workstations in orderto consult the documentation.Your companys business objectives might not warrant theuse of a wiki – whether its open to external users for editingor not. In larger enterprises, it can be difficult to persuade thepowers-that-sign-your-cheques to try something new. On topof that, some departments in larger firms like to keep theirmagic or their kung fu to themselves.© 2009 Scott Nesbitt Thinking Outside the Book - 11
    • Contact UsWeb site:http://scottnesbitt.netEmail:scott@scottnesbitt.netBlog:http://weblog.scottnesbitt.netTwitter feed:http://twitter.com/ScottWNesbitt© 2009 Scott Nesbitt Thinking Outside the Book - 12