Documetation or the Difficulties of Technical Writing
JCrete 2014
Documetation or the Difficulties of Technical Writing
| Documetation or the Difficulties of Technical Writing | |||
|---|---|---|---|
| Convenor: Kirk Pepperdine | |||
Participants:
| |||
| Summary:
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.
Discipline 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: leanpub.com 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 leanpub.com 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
ctually reads it. (Sollbruchstelle - intended to break, planned beakage)
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 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. | |||
| Recommendations:
Biggest takeaway from this session: write small, write often, be inspired | |||
