Documetation or the Difficulties of Technical Writing

From WikiEducator
Jump to: navigation, search

Documetation or the Difficulties of Technical Writing
Convenor: Kirk Pepperdine
  • Geertjan Wielenga
  • Steven Bufton
  • Heinz Kabutz
  • Maxi Kabutz
  • Kerstin Buchacker
  • ...

Audio recording

Documetation or the Difficulties of Technical Writing - JCrete2014

Free content media streamed from Wikimedia Commons

Download: .ogg

Participant Background on Technical Writing

Geertjan and Kirk have already written technical books, other participants have written papers for conferences, articles for magazines, technical product documentation, blogs, tweets, email newsletters, essays for school.

Technical Writing Difficulties and Approaches

Writing is essentially a creative task.

  • often difficult to get started on an article
  • difficult to come up with a good article (for a print magazine) every month
  • often many rewrites of an article before it reaches its final form (seems like a waste of time)
  • If something is intereting for yourself, it is probably ineresting to others as well.
  • Geertjan: When I write, I always have an idea that I want to share. I started blogging to have a place where to put code snippets which I found useful.
  • Kirk: One of the better books I've ever read was the enterprise integration patterns, written by two authors together. They wrote a whole series of blogposts in a wiki style format which poeple could comment. Then they took this material and created a book out of it.
  • writing seems to be easier if you do it regularly, and having a good rythm of writing (like Geertjan blogging at least once every day) keeps you in the zone.
  • arbitrarily imposed deadlines and styles (e.g. book editors may give you rbitrry deadlines, and impose specific styles (to make the book fit into a series))
  • use dictation software such as dragondictate to capture documentation; this may overcome the problem that non-touch-typers may have in producing documentation quickly.
  • often difficult to be productive within strict limitations (word budgets, deadlines)


Under this topic the pros and cons of word budgetting were discussed. There seemed to be a general consensus that while word bugdetting may help you be concise, you should not be forced to use up the complete word budget if you can express your idea well in less words. Interstingly, some modern communication means impose very strict word budgets (e.g. twitter).

Sometimes also the document structure may be imposed. This could ensure that all important aspects of a topic are treated.

Document Types

Time-to-market, reader feedback, shelf life is very different depending on the type of document being written. With time-to-market we mean here the time between when the author's work is done and the document becomes available to readers.

Printed books: In the experience of the participants, traditional printed books usually have a long time to market (months). Reader feedback happens rarely or not at all. Especially highly technical books (the example given was performance) often have a short shelf life, as their content goes out of date quickly. Royalties for the author are rather low.

Product Documentation: As a technical writer of product documentation (delivered with the product to the customer), the only reader feedback you receive is often only the negative feedback, when customers/users complain that the documentation is incorrect.

Online books: allows you to write a book directly in the browser on their site. You are expected to parts of it on the website as soon as they are written. You are expected to keep on updating the book after you have published it. Readers are more likely to provide feedback, point out errors or suggest topics for subsequent chapters. At royalties for the author are 90%.

Online Tutorials: Readers expect tutorials to be updated for each product release.

blogs: The expectations are much lower for a blog, and readers don't expect the author to maintain the information in a blog entry. Time-to-market is nearly immediate, and reader feedback can be fast as well through the commenting functionality of blogs.

Microblogging is not going to replace the in-depth articles or books. Although Heinz newsletters are relativiely short, a lot of research goins into them.

Maintaining Product Documentation

Product documentation may be scattered around a number of different documents and tools, especially when the product evolves over several years. Example: Original product specification, which is several years old, is still available. Change requests, of which there are a large number, are in separate documents, or in tools such as Jira. The company is now racing to put something like the current complete system specification together.

Developers should be maintaining some documentation but often they don't. Also working procedures are often not documented, which leads to loss of time as well as mistakes , especially when personnel rotates often, knowledge is lost and the weel re-invented regularly.

Document Reviews

  • When you write a book the traditional way, you have a lot of commenting back and forth with the reviewers.
  • If you put jokes or other in your technical documents, you can check in a way that somebodies a

ctually reads it. (Sollbruchstelle - intended to break, planned beakage)

  • problematic if non-technical people try to improve the quality of your technical document

Durable Formats

We discussed about how to come up with an electronic format which can survive a few hundreds of y ears and still be readable (there are after all paper books that old and readability is not a pro blem). Some companies specialise in migrating electronic legacy formats into formats which are readable with current tools.

Kirk's suggestion is that for now, keep the information so close to plain ASCII as possible It may not be the only problem that the document format goes out of date, but even if you still c an access the documents it won't always provide you full picture of the system.


Mindmaps were briefly discussed. Heinz produces his course contents from a mindmap source. This e nsures that the course contents published in HTML reflect the contents of the mindmap. Tools used by participants include vym, simplemind (for the ipad) and Mindmanager.


Biggest takeaway from this session: write small, write often, be inspired