Andrew Etter has written a short, Kindle ebook called “Modern Technical Writing: An Introduction to Software Documentation“. The book is Andrew’s personal view of technical communication, based on his experience of being a technical communicator in Silicon Valley.
It neatly describes the “Docs-like-code” approach to technical writing, and it challenges the impulse to write about everything. It describes Andrew’s experience of creating documentation in lightweight markup languages, such as ReStructured Text and Markdown, and using GitHub and static site generators to manage and publish the content.
Overall, I enjoyed reading the book. Andrew describes the benefits from following his approach. Ideally, I’d like to have seen more information and evidence to justify his opinions against other authoring tools. Microsoft Word might be a better choice than Markdown if you need to include complex images, tables or numbered lists. A Content Management System might be a better choice than a static website generator, if you want to provide intelligent content that modifies content to suit different users. The need to manage localised content (in multiple languages) might be easier to accomplish in DITA or MadCap Flare than by using GitHub and Markdown files.
Having said that, the book provides a useful insight into a increasingly common approach to documenting software applications.
Hi Ellis – I read the book last year and agree that it’s a good read. I understand the points you make about certain underlying assumptions but the key points in the book are important and represent a wake-up call for the tech writing profession.
Thanks Fergal. It’s always important to justify the assumptions that underpin a profession.
I know that opinion is somewhat divided but I do think that the tech writing profession is in a transitional state, and the skills required of tech writers and the job opportunities available are changing. I recall that the dot com crash swept away a lot of people from the profession but the current landscape looks even more threatening although there are opportunities for people who are skilled and adaptable.