{"id":3694,"date":"2009-12-11T12:50:45","date_gmt":"2009-12-11T18:50:45","guid":{"rendered":"http:\/\/www.redmonk.com\/cote\/?p=3694"},"modified":"2009-12-11T12:50:45","modified_gmt":"2009-12-11T18:50:45","slug":"links-for-december-8th-through-11th","status":"publish","type":"post","link":"https:\/\/redmonk.com\/cote\/2009\/12\/11\/links-for-december-8th-through-11th\/","title":{"rendered":"Links for December 8th through 11th"},"content":{"rendered":"

\"The<\/a><\/p>\n

A little something extra…<\/h2>\n

Back when I was a developer at BMC, I had the chance work with Anne Gentle<\/a>, a technical writer who did the techpubs for some of the projects I was involved in. As she outlines in one of the below links<\/a>, I remember having fun discussions with her about moving techpubs out of the PDF and Microsoft Help formats they seemed tragically locked in. While I wondered down the hall to get another cup of coffee and go code up silly things like a PSL perser, Anne took those discussions and her experience working on an Agile-driven (Scrum) team there and ran with them over many years to figure out what Agile technical writing should look and feel like. <\/p>\n

Her book on the topic – Conversation and Community: The Social Web for Documentation<\/i><\/a> – is the only treatment of the topic I’ve ever come across, and it seems to be a fantastic manual for jump-starting into Agile documentation. As with so much of Agile Software development, much of it comes down to cultural shifts and tweaking old notions of what’s “not good enough” or down right unacceptable behavior. As technologies evolve – like wikis and social networking – old constraints that drove old process are removed. The process and cultural changes needed for organization keep up usually far, far lag the tools available. I’m hopeful that Anne’s book and work in the area will help on that account.<\/p>\n

The world’s hunger for better documentation and help in the tech space is insatiable, and the traditional methods simply can’t keep up anymore. As a simple example, think how often you go to your digital camera, DVD, or TV printed out manual for help vs. Google. Manuals are the last place I look because they’re usually terrible from the start and not detailed enough in a human voice to be helpful. As a counter example, I always cite my Edirol R-09HR<\/a>. It’s a great gadget, but what makes it the best audio recorder I’ve ever used is the manual. The manuals explain<\/a> how to use all the various settings in different scenarios from recording birds, to music, to concerts, to voices. Especially the aptly titled “Practical Usage Guide.”<\/a> As a simple example, instead of saying such and such menu option allows you to switch between recording in WAV vs. MP3, the R-09HR documentation tells you when a WAV would make sense vs. an MP3 and the trade-offs you can use to make an informed decision on your own.<\/p>\n

That’s a small example, for a relatively simple device. But getting to that usefulness and passion for docs is something that traditional technical documentation practices don’t seem to get to. Hopefully Anne and co. can help change that.<\/p>\n

The Links<\/h2>\n