So I promised I would talk about new tools...and here it is.
While I absolutely subscribe to the notion that content creation and not tool mastery is where writers need to be focused, staying up with emerging delivery trends cannot be avoided.
When developing for a highly technical software programmer audience, for example, delivering a PDF and a help file at this point is an embarrassment.
Developers normally need an API to work with your product, and the best way to document is not to silo your information into categories and publishing formats that don’t play nicely together. After all, who likes to have to copy/paste/reformat line by line from one format to another while trying to write a code example or learn how to program something?
The more fluid Agile approach would suggest that real time updates to Wiki platforms or Git repositories makes more sense.
Let’s think back to where we have come from. Let’s think ahead to where we are now. Yup, you guessed it...content convergence…
Technical writers, developers, QA and customer support all working together to create one streaming, updated, relevant, easy to use portal of knowledge. Last week, I blogged about the new content convergence of webplatform.org, proving that the big companies get it. It should all be fluid and exist in one shared space. The age of the content silo is over. The age of delivering dead PDF files to software developers is over.
Hello Git. OK, just so you know, I love to say it. It is one of those therapeutic words that roles off the tongue. In addition to the oral therapy though, Git is all things wonderful about content convergence. Git is an open source community where a million geeks have contributed to making a fabulous place for programmers to store and file their code. As a side benefit, they can also document the code right inside and then publish the documentation to really awesome wiki like pages, all from within one tool.
Old school: Beg the code from your developers, move it into another tool (Word/FrameMaker/Author-it/HTML) and we’ll try to stay updated as developers change code on a constant basis. Developers get frustrated, tech writers get mad at being left in the dark and the end user suffers from inaccurate, low level documentation maintained in a separate silo. Writers work outside of the development cycle in a vacuum and chase information and updates. Even after your company spent loads of cash writing the API Guides, end users/customers complain constantly that, code is out of date, wrong and not easy to use in real world scenarios.
2012 school: Fork a Git (fork=copy) and store your documentation with the code. Your technical writer spends no time moving content, chasing content or verifying content. They document in the same tool, publish using the same tool. Code snippets come out well formatted, color coded and ready to be used as people use your code and examples. All of the great features within code CMS tools are already pre-loaded in Git work environments.
So what is stopping everyone from moving quickly over to a new API authoring paradigm? Fear of change, lack of technical knowledge, fear of the unknown? If these are the issues plaguing you or your team, you are in luck! Lynda.com is currently offering a totally free 6 hour Git essentials training course (expires October 26, 2012). So now you have no reason not to get on the Git bandwagon and go.
Tech-Tav is excited to be working on so many customized Git integration projects right now and can’t wait to do more. If you want to make a move or just talk about the possibilities but don’t know where to start, we are just a phone call away and happy to help.
Let’s GIT started!