I spent considerable effort writing the user guide for MageSend and have been happy with the results. I think of a well written user guide as the fence-at-the-top-of-the-cliff that prevents the support email burden ambulance-at-the-bottom. It’s been a source of fairly regular positive feedback from customers, so I wanted to share how I created it, and how I ensure it’s seamlessly integrated with the packaging process by build script. In this post I will run through how I use Google Docs as a documentation tool for my premium MageSend email extension, and take advantage of the publish URLs in build scripts to ensure the latest version of the User Guide is packaged in both PDF and HTML format with each release. I will say I only have one premium extension (currently) and am relatively new to this game, so it’s entirely possible there’s much better ways to do this, in fact if someone has some better suggestions I’d love to hear them!
Writing Software Documentation in Google Docs
In order to even go down this route you have to be comfortable using Google Docs for writing technical documentation. I’ve been using Google Docs for as long as I can remember, when weighing options like markdown, plain-html or Latex I had no hesitation with Google and understood the limitations, and advantages of Goole Docs, summarised below.
- + Collaborative editing, e.g graphics designers can add logos and screenshots into the same document as you edit the words
- + Always saved, revision history available for change tracking
- + Simple UI for editing documents, provided you keep your style very simple.
- – You have to get into bed with Google – it’s not a complete lock-in though, you can export plain (but ugly) HTML.
- – Annoying export bug with published docs table of contents linking to the web version.
So it’s a simple, easy to use document editing tool, with a number of modern features for collaboration and exporting, but a few annoying bugs, and slight pangs of vendor lock-in.
Continue reading Using Google Docs for User Guides and Documentation in Build Scripts