The Case of the Stolen Documentation
January 6th, 2010 | Posted in blog 12 Comments »
Turning the Corner on Client Ownership
After I had my documentation theft experience, I started to prepare proactively for similar situations. I realized more of the advantages of having clients maintain the documentation themselves. In addition to being close to user needs and processes, having clients own the documentation also lightens my project load. This is an important point, not just a matter of laziness. The longer you work for a company, the more projects stack up. Minson says,
As time goes on, if you’re maintaining the documentation yourself but you’re also taking on other projects, you can end up with an extensive vault of projects to maintain. You may start to be pulled in many different directions.
The more projects you finish, the more projects you have to maintain. Pretty soon you’re being pulled in twenty directions at once and you don’t have any time to write new documentation, because you’re making small updates here and there. Though the updates are minimal, you have to understand all the implications of one update in the context of all the other content.
In my situation, I’m one of eight technical writers in an organization of 5,000 plus employees, with an IT department of about 600 IT professionals. I want to spread out my talents as far as possible. I’d rather write documentation for 17 different departments and have it poorly maintained than only stick with 3 or 4 projects and maintain them all myself. It’s a matter of influence. You can keep a tight hold of several rocks in your hand, or a loose hold of a dozen.
Directions Toward Collaborative Authoring
Collaborative authoring doesn’t extend only to pre-release writing. That mindset is founded on the assumption that documentation is finished once the software is released. In reality, collaborative authoring includes authoring both before and after the software is released. Before because you want to ensure the documentation is as accurate and complete as you can before releasing the software. After because inevitably you’ll run into gaps, user questions, quirks and bugs, and other tasks needing explanation that you didn’t anticipate before the release.
If you’re stuck with costly proprietary tools that require local installation and training to understand, your attempts at collaborative authoring may end up like the experience I described earlier, where your source files are suddenly “stolen.”
But I only had to give away the source files because the platform for documentation (Adobe InDesign) didn’t allow for collaborative authoring. In order for the business department to collaborate in the authoring process, they had to “steal” the files. The InDesign platform falls under the old paradigm of a one-author, one-tool workflow.
After they took the source files, I adopted a new platform for my projects: a wiki platform based on Mediawiki. (Don’t criticize my choice of wikis; it’s merely the allowed wiki platform for my organization.)
With a wiki, I can collaborate before and after the release. Clients don’t have to take the source files from me to contribute, and I don’t have to wash my hands of the project when they take away my files. I can keep tabs on the updates, with automated notification emails sent to me each time the client makes a change. And I can massage their modifications, keeping the style consistent and professional. Updating it is as easy as clicking the Edit button, because it’s all online, accessible from any browser, and tracked with version history. (At least that’s the theory. My head is still in the wiki clouds here.)
Months Later
A couple of months later, I finally received another phone call about the documentation. This time one of the clients asked for some helping updating a web page I had created. They needed new thumbnails and updates to the web text. They also sent me the updated quick reference guides at my request.
To my surprise, it looked good. Totally different, but well-designed, clean, and visually appealing. The authors had elaborated on the written text in numerous places, adding context to make the tasks clearer. I realized that in my desire to fit the instructions on one page, I had taken too much out. But clearly my documentation was still the foundation.
Some decisions confused me, such as the removal of screenshots and images, but overall the effect was similar to loaning my car out to a friend, and instead of getting it back trashed, with dings on the side, and on empty, I received it back tuned up, detailed, and with a full tank.
From my college days, I remember reading a literary critic named Mikhail Bakhtin. Bakhtin argued that diglossia — the presence of more than one voice in a text — is partly what makes the text interesting.
I think the same could be said of technical writing. When multiple writers add their edits to documentation, looking at it from different perspectives and situations, the effect is greater than one author alone can achieve. In this sense, even if you lose your source files, documentation is never stolen, only strengthened.
——————-
Hey, if you made it this far, don’t stop here. I have a whole index of other posts you can read.
Sponsors
Tags: Adobe Indesign, clients, documentation, maintenance, ownership, quick reference guides, Technical Writing, twittersphere
If you liked this post, keep updated with new content: Subscribe to I'd Rather Be Writing.
Both comments and pings are currently closed.
Mark Baker (5)
DiSc (3)
Jen (3)
Neal (3)
Richard Hamilton (3)
Ellis Pratt (2)
Jenny (2)
Sarah Maddox (2)
Sarah O'Keefe (2)
Stefan Kleineiken... (2)
Good post, Tom. I think that’s one of the hardest things that tech writers go through is letting their baby get painted another color. It is pushing us, though, to look for more collaborative ways to create content. I’m with you on the wiki train. I’m looking at a DITA to wiki solution. There’s a tool to help if you use the Confluence wiki. I haven’t tried yet, but I will within the next week. The problem I’m facing is the return trip. I want to have a collaborative environment but don’t know how to get the wiki updates back to their XML home. The conversion tool I mentioned supposedly does a wiki to docbook conversion, but the DITA component hasn’t been completed (supposedly it’s in the works). Also, have you thought about how to handle reusable content that would come from single-sourcing if you use the wiki?
Dan,
There is an open source solution for your use case. The project is called DITA2Wiki and it’s available on SourceForge:
http://sourceforge.net/projects/dita2wiki/
Download the latest DITA2Confluence binary distribution + User Guide PDF.
Installing and importing the demo DITA content to the Confluence wiki should be easy and fast. You’ll find some user reviews here (note that they describe some configurations that have changed, so be sure to follow the instructions in the latest User Guide PDF):
* http://justwriteclick.com/2008/10/16/dita-meets-wiki-output-dita-to-wikitext/
* http://ffeathers.wordpress.com/2008/10/26/playing-with-dita2confluence/
BTW, DITA2Confluence also supports conref (reuse in DITA), which I don’t think any other DITA-to-wiki solution does. The source text–the content being reused–is editable in the wiki output, but all reuse instances are read-only.
Other nifty features include transforming metadata to wiki labels (useful for compatibility information and other categorization).
If you have any questions, ping me at lisa dot dyer at gmail dot com. I can advise you on the round-trip aspects as well.
Cheers,
- lisa
Lisa, thanks for adding the comment about the DITA2wiki plugin. I’ve seen you demo the plugin and have always been very impressed. My main hangup in adopting the plugin is that I’m using Mediawiki rather than Confluence, and I don’t have my content structured in DITA. But I can see how this plugin would be incredibly helpful were a few variables in my situation different.
Hi Tom,
Thanks for the kind words:)
Some good news regarding DITA2Wiki support for other wikis; a Maven plugin of the DITA2Confluence tool is under development, to be distributed as part of the Maven plugin of DITA OT.
This work creates the appropriate architecture for supporting any wiki, enabling the DITA community to “plug in” their own import functions. GA is expected end of February.
I’m hoping that someone will be inspired to contribute an import function for MediaWiki:)
Cheers,
- lisa
Interesting post. The documentation department I work in has a policy of never releasing the source files. This ensures quality (I’m thinking back to your previous post http://www.idratherbewriting.com/2009/04/23/can-others-do-your-job/) and prevents unfinished, unchecked and possibly incorrect (yet company branded and therefore liability-carrying) documentation being “leaked” to customers.
We are always being asked for the source files (including by customers!) but the answer is always no.
Haitham, thanks for your comment. Retaining the source files seems like a good strategy for a number of reasons — you protect yourself from brand misrepresentation, you maintain your role as the designated producer of the information, and you can keep a tight hold on style and structure. The only weakness is the lack of collaboration. If the SMEs have info you need, collaboration can be extremely helpful. If you already have the info, collaboration is unnecessary.
Tom,
I have been reading your blog on and off for a few years and this is my first comment. Since I write some manuals myself I have also been stuck at the same situation, both on the stealing side and the stolen side. You are absolutely spot-on about the ownership thing – we should at least be lucky that we are dealing with more background stuff (manuals) than copies on the spotlight (web copies, packages, so on). I think one good thing in those situation is that nobody is trying to make things worse – they all believe they are doing the best for the outcome, even if it is identical with his personal preference. I am thinking open, collaborative editing might be the way thanks to you. We may have InDesign as a web-based app soon, which will make things more easier.
Tom,
Go here and read:
http://www.scottburnham.com/files/Scott-Burnham-Hacking-Design-2009.pdf
Now think about users taking over the information you produce vis-à-vis what Burnham says about hacking as “overcoming the limitations of an existing object, service or system which was set for one purpose, and finding an access point, intellectually or physically, where its original function can be expanded, altered, or improved to serve a new purpose or solve a problem”.
Do you see any of that happening with the documentation you hand over, either now or in future?
Interesting post Tom, keep up the good posts!
I used to get very proprietary about my manuals and as 100% of what I do is for clients I can’t exactly demurely decline when they want their source files. Two things happened in 2009 that changed my opinion on releasing files to clients. The first was a disaster for my client – a large restaurant chain. They had an internal person do their operations guide and then allowed it to get 5 years out of date. When they wanted me to create new material and incorporate the old material the only thing available were pdf copies – they didn’t even have the ability to update their own recipes. This client had to go through the trouble of doing a large search for the long-gone employee to see if they had the files since they did not want to pay to convert the pdf files. The second instance was a new client. I happily turned over their source files and they promptly totally blew them up by trying to change the formatting and not understanding the underlying structure. I now am on a document maintenance retainer with them. Sometimes letting your client make their own mistakes is actually beneficial to their understanding that documentation is not in the category of glorified-typing-pool product. I’ve gone to building in a teaching component into my project prices and I’ll spend time with my clients teaching them how to maintain their own docs.
Our department doesn’t create documentation for external clients, but we have had a couple of online Help systems “hijacked” by well-meaning but poorly trained software engineers. Reading between the lines, I think those engineers were trying to bypass the standard procedure for having TechComm write the online Help (read as: software project manager didn’t budget for it). I’d never seen a well-written online Help system get turned back into an acronym-filled, menu-descriptive specifications document before!
[...] this year, Tom Johnson in his blog “I’d Rather Be Writing” discussed the issue of documentation ownership. He had recently handed over the source files of several manuals he had done to an internal client [...]