ExpressionEngine Client Documentation

Great post, count me in! It’s comforting to hear that you also get the annoying phone calls from clients before they attempt anything…*i guess misery loves company*. You’ve inspired me to write my own documentation which I plan to share with the community as well! Thanks Emily

For every site I build, I include a predesigned user-guide template which has an index page that links to three separate pages - a general user guide which describes publishing, editing, closing entries etc and how to use TinyMCE and TinyBrowser; a video guide which covers most of the stuff described in text in the general guide and then a site-specific guide which runs through all the things not covered in the other two.

The site-specific guide is an entry in the site’s database. I use screenshots for it and the general guide wherever possible to illustrate form fields, buttons etc.

The other two are actually pulled in via AJAX from a different location which means that I only have to write those guides once and they can be used for multiple sites. It also means that if I edit the guides for whatever reason, I only have to edit them once and all sites get updated.

In a lot of cases for the site-specific guide, I also link to images of buttons from the central location so as to not have to repeat creating the images.

I also use MD Dulee Noted to add an instructions field to all publish/edit forms with a link to the user guide in big bold text, so it’s right there in front of people when they’re creating/editing their entries.

John, that sounds incredible. Would you be willing to share your templates for this…? and how you set it up using AJAX, etc?

Training and EE documentation is certainly the most painful part of web project for me. So I’m very interested in how others are doing it. I’ve been using Skitch and Pages to create a PDF document that I link to in the control panel.

John, I too am interested in your method and I’m willing to bet there are many EE users that would be as well. In fact, if you were reasonable about it, I’m sure you could monetize your product.

There’s no real product as such; there’s just a fairly ordinary EE template with a bit of jQuery AJAX code, and a single PHP file which I found to enable cross-domain AJAX calls.

The EE template is pretty simple and just uses a conditional that determines:

- If segment_2 is blank then display the user guide home page with links to the pages.
- If segment_2 = section-specific then use a weblog:entries tag to display the only entry in the user-guide section.
- if:else (for the other two pages) do this:

<div id=“your_AJAX_loaded_content”></div>
[removed]
$(document).ready(function(){
$(”#your_AJAX_loaded_content”).load(”/path/to/transport.php?url=http://www.url_of_your_docs/{segment_2}.htm&method=get”);
});
[removed]

The important thing to note about the last part is the transport.php, linked at the beginning. So /path/to/transport.php is on the server for the site you’re adding the user guide to and http://www.url_of_your_docs/{segment_2}.htm is the URL of the central location where you keep the documentation, and I’m using the segment variable to help identify which .htm file to load.

And that’s it.

Also, make sure you have template access to the user-guide template group restricted only to members who would be editing entries.

@John what a good idea to use a centralised location for your general documentation. Is it not possible to use file includes from other domains? I’m presuming that must be why you’re using this AJAX method.

Thanks for sharing your approach and some of the technical details too.

You could do it with PHP using allow_url_fopen or allow_url_include maybe, but not all web hosts allow these for security reasons, so another alternative is to use cURL which is what is used in transport.php anyway. I didn’t actually think about doing the inclusion completely by PHP, it’s maybe something worth looking into.

I love the look/feel of Headspace’s guide, and perhaps that makes sense when you are delivering a final product to a client and moving on.

In my case, I continue to develop and produce content for an EE site and an in-house web dev.  Documentation changes frequently and it’s become really clear that if I want people to actually produce web content I have to make it REALLY easy. And now I’m going on maternity leave, the documentation pressure is ON.

I have found a lot of folks using the Wiki module for this (I’ve also hear of people creating a documentation weblog/channel) - wiki is where I’m heading. I’m sure a lot of the info from the Headspace docs (very gracious of them) will help me populate it though. Additionally I link to screenshots of examples or specific wiki pages in field instructions as applicable and use MD Dulee Noted to remind folks the key topics for the form (linking to the wiki).

Videos are great for making people feel more comfortable. I’m very inspired by MailChimp’s control panel with inline video tutorial links and would like to figure out how to display videos in a lightbox right on the CP.

I just do a quick 15 minute screencast using Screenflow. I run through pretty much every task, using their own EE install in the video, then pop it on a URL on their server - typically http://example.com/training.

Works a treat, is highly customised and takes almost no time at all.

Hi there. Just letting you know that I’ve provided a free, re-brandable update to the ExpressionEngine Client Guide, now updated to EE2.

Feel free to download and share - all I ask for is a link back to the site if you can. Enjoy!

http://headspacedesign.ca/blog/entry/the-expressionengine-2-client-guide-is-here/