Posted on

Using Google Docs for User Guides and Documentation in Build Scripts

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!

MageSend Documentation

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

Posted on

Improving Magento ImportExport module with Better file format and Google Docs integration

In this post I’ll run through two ways that we improve the default Magento ImportExport module when importing products to Magento stores. The two improvements I’ll cover are: importing directly from a Google Docs spreadsheets and improving the multi-line format to make generating the import files easier.

Background to the Magento ImportExport Module

The ImportExport module itself is such a drastic improvement on the old DataFlow module it’s almost unbelievable, so let me first start by saying it’s not half bad to start with. Andreas does a brilliant job of describing the current file format, it’s in German but Google Translate plus the excellent example tables will make it quite readable. Vinai’s presentation at Magento Imagine 2011 is also required reading to understand how the new module works, and most importantly how easy it is to extend.

The two things I didn’t really like about the current functionality were the need to get a single local file to the server for processing and the multi-line format for configurable products and multi-store/site/category/image products. Here’s the changes made to improve on these.
Continue reading Improving Magento ImportExport module with Better file format and Google Docs integration