Tag Archives: Confluence

techpubs wiki writing

Must Read: Confluence, Tech Comm, Chocolate

“Who cares about printing money, let’s print chocolate!”

–Chapter 23, Driving Wiki Development, Confluence, Tech Comm, Chocolate

Do you need proof that Sarah Maddox, author of Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication, is a complete chocolate and wiki expert? Let me tell you, she knew that one day we will print chocolate in our (industrial-grade) kitchens. And sure enough, that day has arrived! And so has her book. It’s a wonderful addition to the XML Press family.

Sarah has an amazing knack to start at the beginning and introduce wikis in a friendly way even though she has been living the wiki life for years. She writes an introduction to wikis in an approachable way and ensures the reader knows the context is technical communication. But for me there are technical details revealed that offer the best chapters of this book. There is the deep technical dive into “building online help” especially her case study of web-based, context-sensitive online help. This solution should rock your world if you’re looking for a cross-platform web delivery of your online help. Her chapter about “a day in the life” of the wiki is just what you need to understand how this delivery and collaboration solution is different from “ordinary” technical writing. And I thoroughly reviewed and enjoyed “Giving your wiki wings.” Wikis with wings are the way technical writers will show their value to the world. I especially appreciate the chapter “Driving wiki development,” where Sarah is clearly honest about gaps in wiki functionality and how we can actually improve our experiences with wikis.

This book is an important, essential addition to the professional writer’s bookshelf. I’ve already whole-heartedly recommended it to an entire team of Rackspace writers and to all my Austin-based writer friends who have listened to me talk about the changes in the industry over the years. I want to recommend it to all of you as well. This book offers both visionary inspiration and the nitty-gritty technical details for all of us working in this web-centric world. I have so much respect for Sarah’s work on this book. Her enthusiasm for the wiki way shines through each page – web page and printed page. Pick up a copy, devour it like a chocolate bar, and drive collaboration for technical content.

Buy now at Barnes and Noble

Buy now at Amazon.com

techpubs tools

Why You Might Care about the Cloud

Talk about clouds, hybrid clouds, private clouds, and suddenly throw in software as a service and platform as a service, and you might be wondering, what does it mean? Whoa double rainbow, as some would say.

I wanted to put some perspective on the cloud for technical communicators. I’ve had a great guest blogger post from Ynema Mangum about cloud computing in the past titled, Clearing the Air on Cloud, but when I saw Ellis Pratt tweet about using the cloud for one of his projects, I followed up with him to learn more. Here’s an interview with Ellis Pratt of Cherryleaf about his recent experiences with cloud computing.

Q1: Could you describe the project when you recently used a cloud computing environment?

We’ve created a report publishing system, based on Confluence for a client. The reports are fire risk assessment reports, so they want the ability to complete the reports “on the road”.

Q2. What compelled you (or required) the use of virtual computers available on a network for the project?

We put a version of the prototype in the cloud for a number of reasons:

  • The client’s IT person hasn’t yet installed Confluence on their Virtual Private Network (VPN), so to keep the project rolling along, we created a version in the cloud that they could access and review the prototype of the system.
  • We’d also outlined in our proposal how they could host the system in the cloud instead of on their VPN, so it gave us the opportunity to show them what it would mean for the report writers.
  • Our own VPN can be slow at time and holds sensitive data, so it was an excuse to test out the potential of a hosted application server for our own use.
  • There may be cases in the future where clients would want to access a documentation solution hosted by us, so we wanted to research the possibilities and potential.

It was prompted by:

  • A chat I had at a 4Networking (business networking) meeting with a software developer, who said how cheap it was to create a application server these days. We’d looked at it about 6 months ago (when we put our file storage in the cloud), but had found it a bit too pricey. The prices have seem to have come down.
  • A blog on the Confluence blog about how you can turn an application server on and off, so you’re only paying for it when you need it.
There was also an underlying interest. We’ve been working on making it possible to work away from the office for longer periods of time. There’s a quite a difference between working off-site for a day and working off-site for a month.

Q3. Have you seen the Microsoft TV ads with the line “To the Cloud” (link)? What’s your reaction to that type of consumer messaging about the cloud?

Those adverts haven’t been running in the UK, as far as I am aware. The message seems to be the cloud is for when you’re up against a deadline and when you want to be cool. I suspect its aim is to get  non-technical people to associate the word “cloud” with Microsoft, so they go to the Microsoft site if and when they want to investigate what “the cloud” is.

It doesn’t tell you what the cloud is. Collaboration can be done on a LAN, a VPN and a wiki, so it doesn’t tell you how it differs from those options. I guess the key message to the consumer market is: work on any computer, anywhere you like. I’d like them to make some comparison to Google mail (or Hotmail), as many people will have experience of that.

Q4. For tech comm, do you think relevance to cloud computing lies in collaboration (access to more people and networks) or scale (access to more computing power) or another aspect?

I’d say collaboration, bypassing the IT dept (!) and the ability to work from home.

Q5. What’s a great way to introduce cloud computing to technical writers? How do you make it relevant?

I’d suggest real-time collaboration, the ability to work from anywhere, the ability to have a fast system, the ability to test software among a group, user generated content and the ability to make stuff web accessible in a way that doesn’t put any company-critical stuff at risk.

Q6. Do you agree with the statement “cloud computing is becoming “the 21st century equivalent of the printing press” from Nicholas Carr’s blog entry, The cloud press?

No, I believe collaborative authoring/cognitive surplus/wikis are the 21st century equivalent of the printing press – a low cost way to get more people to write (and read) more quickly.

The article does raise the Wikileaks/Amazon issue. Putting the rights and wrongs of Wikileaks aside, Amazon’s actions do show that cloud providers can terminate their service to you in an instant, if they choose to. Although it’s unlikely that many of us will host any thing as contentious as Wikileaks, it will lead people to ask, what would happen if they did pull the plug on us? There are also national laws to consider around data protection – EU laws, the Patriot act etc . We have our cloud data hosted in the European Union, for example.

Q7. How does cloud computing affect tech comm delivery?

It makes user generated content and a more distributed authoring team more possible. It makes it easier to get contractors to use your software.

It means we can do more Webby things with documentation.

The biggest challenge we faced was setting up the server. You can end up in this no-mans land between the hosting service and the application vendor where there’s no-one document telling you how to install the software in the cloud. It’s easier with Windows Server than with Linux, but then you’ll be paying more for your hosting.

Thanks Ellis for sharing your perspective and experiences!

wiki

The Rockley Blog – wiki’s delivery mechanisms

I’m thoroughly enjoying the new Rockley Blog at http://rockley.com/blog/. I’m so glad Steve Manning and Ann Rockley are blogging, especially about wikis.

I appreciated Steve’s post “Wikis for Documentation” especially where he says that the delivery side is the weak point still. Agreed, but I have seen pockets of improvement there and need to be blogging heartily about them.

About three years ago I was equally as unconvinced of a wikis usefulness for end-user doc. An Agile-advocating developer mentioned the idea of using wikis so that the end-user doc could stay in sync with their fast Agile iterations. Yipes I thought! Wikis did work well for convincing the developers to contribute their knowledge, though, and internally they became a useful knowledge sharing (and finding) system.

Now I’m starting to see more and more actual customer need for them. I just had a great discussion about the difference between what a customer needs and what a customer thinks he or she wants, though, so some of what’s necessary is interpreting whether a wiki can fulfill a customer need. I got a small chuckle out of the title of this blog entry – Wikify Documentum Already – but he’s talking precisely about the gains you and your customers make when documentation is in a wiki. The interesting momentum going now is whether the current large enterprise content management systems can start to see the value in a wiki output, or whether the wiki engine providers themselves are going to catch up with the full feature set available in the large enterprise systems.

But wow, I’m learning how difficult wiki maintenance and trust patterns can be while using the wiki.laptop.org site to help out with their end-user doc. In some ways, wiki doc is more difficult than using the real CMS tools that we’ve become accustomed to (read: spoiled by). But I’m also learning how amazing the collaboration opportunities are when using a wiki. I’m still marveling at the communication going on in the discussion pages as well as the volunteer spirit that has come through a request on an art network.

So, what to do to get decent output for content delivery using the multiple channels that us advanced single-sourcers are already accustomed to? I’m planning to move the XO’s end-user doc towards the Flossmanuals.net model of a highly customized Twiki implementation where you can get and print a PDF from the wiki. I can’t wait to learn more and I’ll blog about it as I find out. It’s a step in that direction, though, where you deliver user guides and online help and web sites tailored to the needs of specific audiences. Language translations in a highly distributed environment are going to be an important part of the project, and I’m curious about how Flossmanuals provides for that aspect. riverbend.jpg

I’ve learned that you can write a Confluence plug-in that will take DITA source and turn it into wiki text. Confluence has PDF output capability as well, so it’s another step in the right direction to get that just-in-time content delivery that a customer needs (but doesn’t know that they want.)

Putting documentation in a wiki (or any really-well-indexed web location, really) can increase findability. If you get internal comments that say “you haven’t documented this particular feature enough” and you feel the feature is sufficiently documented, examine the findability of your documentation.

Also in our user advocacy role we are learning how to listen to customers and then interpret their needs. As information acquisition continues to gather speed, we not only provide the information but should also make informed choices about delivery methods.

Examples of what a customer wants but might not know that a wiki can deliver:

  • What’s new with the product?
  • How do I interact with documentation, support, the company represented as an actual live person?
  • I want immediate information updates.
  • I want to discuss the nuances of an implementation decision.
  • I need to find others who are attempting what I am in the same type of field (insurance or banking).

What are your thoughts? Are we spoiled by our advanced delivery systems and waiting for wiki engines to catch up? Or are wiki authoring and delivery systems already giving us collaborative opportunities that are unparalleled?

writing

Podcast about wikis with Tom Johnson at TechWriterVoices.com

Everyone, please give the TechWriterVoices.com site a look or two or three or more. It’s such a great site. I’m not just saying that because I have a podcast there now, Answering Tough Questions about Wikis – Anne Gentle, but because I do want to tell everyone what a great interviewer Tom Johnson is.headphones

Tom sent ten excellent questions ahead of time via email and I spent some time answering them by writing out some notes. I’ve sharpened them up for those of you who, like me, don’t really have the auditory learning style that listening to podcasts serves best. I always want to be able to scan my media and pluck out the pertinent tidbits, and few podcasts have that feature. (Side note: with QuickTime movies you can make chapters which allows you to scan the chapter titles for the content you’re most interested in.)

So, here’s the interview in text form, but not a complete transcript. We skipped around, Tom edited around the audio difficulties, and sometimes I just answered the question differently.

1. How we can manage and re-use content when it’s wrapped up in mediums like wikis? Can you single source topics? Can you export the content to Word? Or is it locked in its own format?
Nice lead in. This is the ultimate question that many people are asking me and I am having lots of conversations via email and lunches, trying to come up with ideas.

Wiki engines are becoming more and more powerful and CMS-like. WikiMatrix.org has 95 wiki engines listed as of this week. Yes there are still very simple wikis but there are also people making wikis run really powerful websites with amazing wiki extras – like threaded comments, conflict resolution, and so on.

But about single sourcing and wikis…

One idea is that you export your source to a wiki, and then when any changes come in, have to have a human cull through all the edits and figure out what should go into your souce files the next version of the wiki should be, like book publishing. This method is similar to going through support forums or support call logs to see what you’ll include in the next version of your book. Lots of work and thinking.

Another idea for single sourcing a wiki is that the wiki files themselves are the source – if we could invent a DITA wiki where a webform is used to edit DITA topics then we’re there. The wiki platform would also become a publishing engine. Also Confluence appears to work on this idea, that the wiki files are the source and you can publish out to PDF.

Paul Kandel at Intel has this idea that you’d have an offline wiki, with synchronizations every once in a while (you’d set the time parameters). He’s talking about the Dojo Offline Toolkit ( http://dojotoolkit.org/offline), which is based on Google Gears (http://code.google.com/apis/gears/ ), could provide an outstanding solution to the issue of generating offline doc formats. You could enable the wiki itself to be viewed offline, and user additions could automatically synchronize with the online version. I’m not sure I fully understand the advantages and disadvantages here, but the source could be “frozen” in time every once in a while.
Another idea is to be very selective in what you put in a wiki, and make the wiki the source for that selective info only.

Many wiki platforms have import and export capability. However, as my co-worker Mary said on the Author-it users Yahoo group, try not to have your precious content be downstream, meaning, if someone asks you to export all your Author-it topics to Word so that they can be imported into Wikimedia, try to find a way to have the content go the other way around (export Wikimedia content and then import it into Author-it).

I’m also working on the One Laptop Per Child project which is an education project to provide opportunities for children to explore and express themselves. It’s a neat project where we would really like to figure out how to go from wiki content to Author-it and then use Idiom for translation… but it’s probably a “copy from the OLPC Wiki and paste into Author-it” method because the wiki.laptop.org content is not written for the audience we have in mind. The docs for the kids are translated into at least seven languages. It’s an interesting project to be on, and I’m learning so much as I go.

2. You found that with Wikipedia, fewer than 1 percent of users contribute more than half the edits. Should technical writers expect the same 1 percent user contribution effort with the wikis they create?
I just read on keycontent.org that even the MSDN wiki has 5 top contributors. Of the 1876 contributors, 5 contributors (three from Microsoft) made about 1500 of the edits (out of 5800 edits).  I believe you should expect a similar contribution effort as long as those numbers continue to be displayed in other wikis. I suppose the key is recruiting and maintaining relationships with those users. And really, you probably want just a few core inner circle type of people so that you can maintain positive relationships. It’s like an active listserv – you can probably count on one or two hands who the inner circle of contributors are. Those are your experts who are also helpful and giving.

3. If it’s only 1 percent, and your audience is 500 users, that’s only 5 people making edits. Is the wiki even worth it then?

It’s certainly worth it to the 5 contributors who are motivated for whatever reason. And the audience size is difficult to speak to the value – if your manuals had an audience of only 5 people, would you write them anyway? In some cases, yes, because many products need the manual for quality purposes – it’s just an expectation of a software or consumer product. For some products, a wiki is an expectation (probably as an extension of highly visible/visited forums).

I write more about motivations for contributing to wikis in this article on The Content Wrangler. (Think of Reciprocity, Reputation, Efficiency, Attachment to a group).

4. What type of information is a wiki best suited for? Reference? Troubleshooting? Living documents? Why?

I believe that there are several reasons to use a wiki for certain types of information. For Reference information, a wiki is searchable and allows for easy upload of large log files (although if the reference info is in tables, well, I’m not sure how each wiki engine would handle table formatting). Troubleshooting info in a wiki follows the “better than a support forum” model for wiki building. A document that changes often or should change often might be suited for a wiki. Internally, developers can use wikis to explain why the software was designed the way it was, what gotchas in the code to be aware of. Wikis are quick methods for team meeting note-taking and that sort of thing, which would be reference info. So I guess the type of information is the type that people want fast and want to collaborate on.

One person on Gordon McLean’s website onemanwrites said that a wiki plus a Google search appliance is a really good thing. I found that to be the case at BMC for the internal wikis and searching, the combo was killer for finding info or for finding collaborators quickly. That commentor also had the good sense to say “it’s worth watching what goes into it to guard against people setting bad advice in stone.”

5. Is the typical wiki editor robust enough to support all the complicated styling that technical writers do? Can you create your own styles? How hard is it to work with graphics?

Some wiki engines are robust enough… lots of technical writers that I talk to like the Confluence editor’s robustness. I’m not sure if technical writers do much complicated styling really, compared to magazine layouts and glossy brochures. Or if we do need complex styling, the copy is sent to layout.

I’m also not sure how complex tables are in most wiki engines. I think for the most part, you get headings, paragraphs, and lists. Beyond that and levels of those, what else do you need for much technical writing?

Graphics can be a complete bear to get in… apparently one of the Motorola writers had a heckuva time importing the graphics from the user manual into the Mediawiki-based wiki with the time crunch she was up against.

6. Who is actually using a wiki? Have you personally used a wiki successfully for a product?

Many people are using wikis internally. I myself was more interested in wiki use externally for product documentation, and interviewed Emily Kaplan at Motorola and Dee Elling at Borland for information about technical product documentation house in a wiki or wiki-like structure. Harry Miller at Microsoft also interviewed one of the PMs for the MSDN wiki.
Wikis are a favorite quick website set up for many open source-type projects. Also the gaming communities seem to have flocked to wikis either as a replacement or enhancement to customer support or game discussion forums.

I’m using www.imiscommunity.com for my current job, and it’s highly effective for making quick web pages for internal or external use. Plus the search engine is useful. It’s a Drupal site but nearly every page has an Edit tab, so it’s wiki-like.

7. Wikis have been around for 10 years. Wouldn’t they take off if they were going to?
I think they have taken off in certain circles, just not yet in ours. I think that with a set of best practices or push from customers or employers, wikis will be in demand, and it’s a matter of positioning your tech pubs department as the overseers of that content. Without a strong guiding hand, a wiki isn’t that useful because people don’t know what to contribute or how to handle revisions and so forth.

8. What if a user makes a change you don’t like? Do you change it back, offending the contributor? Or do you leave it in, offending the other users? How long do you stick around making these decisions?

I think that you almost need to think of the contributor as a team member, and then behave as you would with a colleague writer. If it’s inaccurate, you change it and reason with the person as to why it has changed. If you’re looking to save time, or don’t have the time to arbitrate, then don’t take long to make those decisions, or don’t get involved with that particular change. But don’t expect to build a wiki and have all these contributions come for free or little resource or time investment. That’s just not realistic.

9. How does a wiki build community?

In itself, a wiki can’t build community. There’s a great quote from Wiki for Dummies with a heading entitled something like “don’t go on a wiki suicide mission.” It says “Wikis don’t have magical powers. They cannot create camaraderie where none exists, nor can they streamline an out-of-control operation. They are not powerful information magnets, nor will they make your team better writers, more organized, or more intelligent. In short, without a strong guiding hand, wikis are useless.

Wikis cannot promise instant returns or unbelievable creativity. Wikis allow users to quickly and easily update and upload information.

I enjoyed the heck out of that quote. But, many web workers are finding that a wiki is a place to find other like-minded individuals trying to tackle the same problems and offering similar solutions, much like a customer support forum. So a wiki can help build community by offering information and identity to the contributors.

10. As a technical writer, are you ever done with a wiki project?

I’d say No. Wiki building is a lot more about relationships and connections so you’d never want to sever those ties if there’s still a bond there. Anyone who thinks that starting a wiki will make less work for their techpubs team by crowdsourcing the writing is fooling themselves. But if you want to serve and connect with a certain set of customers, you’ll do what it takes to keep the wiki alive and kicking.

DITA wiki

DITA and wiki – w/ho/w will (we/you) write

I received an excellent question from a reader about his eagerness to use wikis for his product’s doc set, but he came across conflicts and issues when he questioned the practicality of maintaining a wiki for his large set of documentation. Here’s Paul’s well-phrased request for information.

I am considering using a wiki for documentation projects, but have been coming across some showstopper issues. Here is the story:

Our documentation set is large. We only want to maintain one set of files. Therefore, any changes in the wiki would need to be automatically synched with the source files.

The obvious suggestion is “just make the wiki your source files.” However, it is not as simple as that, for a few reasons.

  • First of all, we need to generate attractive offline documentation in online help format, viewable across several operating systems. No wiki enables an elegant way of doing that.
  • Secondly, we have a bunch of conditional text–our existing documentation comes in six different versions. I have not found a good way to integrate the different conditional tags into a wiki, while maintaining it in both our sources and the offline output files.
  • Finally, wikis almost by nature do not support DITA. Wikis are designed to be simple and easy to understand. However, that approach negates many of the advantages of structured writing.

For these reasons, I currently see wikis primarily as a collaboration tool. But they do not have the features necessary for complex technical documentation.

Do you have ideas for how we could get around these issues?

Oddly enough, on this particular day, another reader wrote in about similar issues with wikis, but they have started to overcome them. He listed the issues succinctly, saying:

I’d say that there is quite an art to creating wiki doc from a couple of perspectives:

* conversion
* building out the infrastructure
* look-and-feel issues
* style issues
* review issues
* basic editing issues

Even with all these issues — :) — however, the immediateness of the experience, the ease associated with making changes and the creation of links and containers, and the modern look and feel really make wikis a fascinating competitor with other, much different technologies. How many other industries move off in such opposite directions (wikis vs. dita)? It’s sort of like trying to figure out whether cars should run on gas or steam!

The CEO of Confluence came through a few weeks ago. He was pointing out to the following as an example of a company that had developed wiki doc:

http://www.gigaspaces.com/wiki/dashboard.action

Here are two more you might find interesting if you don’t already know about them:

http://docs.codehaus.org/display/GROOVY/Documentation

http://www.aptana.com/docs/index.php/Main_Page

And here’s the part that is amazing to me – in a follow up email, Paul answered some of his own questions and said that the gigaspaces.com wiki is one wiki he is investigating further. For example, by talking to one of the writers, he learned that their wiki has 1300 pages, and reuses many pages through the [include] command or transclusion, which is the inclusion of part of a document into another document by reference. My original response to Paul talked about DITA as source files and wiki as an output from those source files. I learned that Robohelp does something like that, with source files and wiki as output, and this blog post mentions round-tripping the content back to Robohelp.

Naturally, I have some ideas about DITA and wikis. My post about DITA Storm built into a custom wiki describes a hybrid approach, with DITA files as the source and editable pages. Paul takes that idea one step further, saying that you could have the internal technical writers see a DITA editor interface to the wiki, but have end-users write doc in a simplified editor with fewer tags. I like that idea.

There’s also the possibility of a transform from DITA to wikitext. A search on the dita-ot-developer list on sourceforge.net revealed that Deborah Pickett was writing such a thing for her employer last April. I emailed her and she generously gave me her XSLT source files, but said that she gave it up when she found that “The whitespace rules for wikimedia meant that anything fancy would end up being better written in wikimedia’s pretend HTML format anyway.” Hm. I haven’t tried the transform yet myself. Bob Doyle has done a lot of DITA to WikiMedia transformation to pre-seed the ditawiki.org with content, and he says “The Perl script for conversion to MediaWiki is publicly available at http://www.jtidy.de/conv. It has a major flaw in that it does not convert URLs to hyperlinks.” Again, I’d need to try it myself to see whether that approach would work and if the technology scripting is worth the effort.

Now, for everyone pondering wikis and DITA, an absolute must read is this great article by Paul Prescod, The Convergence of Structure and Chaos. Not that it offers practical solutions (although he hints at some at the very end), but it maps DITA concepts to wiki concepts.

I’ve also been noticing that people are trying to automate getting content from their support forums into wikis… Check out this poor intern’s daunting task: http://ask.metafilter.com/62679/Automated-Media-Wiki-Page-Creation.

I guess to answer my own question about where wikis fit in tech doc, I currently see wikis as supplemental, not source doc from which to make other things. I probably lean towards seeing a wiki is another output from perhaps DITA source. Sure, there would have to be a loopback mechanism to get the contributed parts of a wiki back to the source files, and I’m not sure how automated that could be. But, I would love it if vendors could convince me otherwise, and frankly, I keep hearing about Confluence and their examples are compelling.

So I share with you these side conversations I’m having in hopes that the information here helps others in their quest to offer wikis to their end-users. Users, write the manuals. But make sure us writers get to meet our objectives as well.

As a final departing thought, I share the machine is us/ing us video, containing the best description of Web 2.0 and new media I’ve seen to date, created by a cultural anthropologist. It’s about five minutes long, and a thought provoking piece.

One of the questions in it that stuck in my mind was the question at about 3:00 minutes, “Who will organize all this data?” And the typed and re-typed answers after a screencast or demo of del.icio.us:

We will.

You will.