Time for a MODX Revolution guide/manual for editors and other end-users

FYI and in answer to ojchris's first question, I currently expect to be working on the manual through October and publish the first draft by early November.

In answer to ojchris's second question, right now I have:

• a four-page document;
• a bunch of notes; and
• permission from Valeska Scholl to borrow, with attribution, whatever I need from her Evo-focused MODX Content Editor’s Guide.

I agree with Susan that Valeska's work is an impressive piece of professional documentation. I hope she's appreciated by the Evo community. (I'm a Revo-only guy, so her guide was new to me.) Now that I have Valeska's permission, I will be taking her work as a starting-point.

As mentioned above, I'm looking for other examples of great end-user manuals. Possibly the best example I know of is the help file on the old CityDesk desktop content management system, which had the virtue of being written by that most engaging of software writers, Joel Spolsky, and which is still online:
http://www.fogcreek.com/CityDesk/2.0/help/

I will be borrowing elements of this for the MODX end-user guide.

Want to help? The most important thing that people can do is to tell me what your users do and what they struggle with most. What do they ask for help with? When do they say "I don't get this"? What do they spend most time on? (My guess is the simple "add an article with an image" task.) What do they do that stuffs up the system? (My guess is "paste from Word".)

I'm keeping an eye on this thread so please post ideas and war stories here.

The best CMS deserves the best end-user manual. [ed. note: shorewalker last edited this post 11 years, 7 months ago.]

My users tend to pick up the creating, moving, and organizing of pages really quickly. Things gum up when it comes to working with TinyMCE and the file browser (both MODX's and TinyMCE's). Working through how to upload a document to link to and then create the link to it is a multi-step process with a lot (a lot!) of modal dialogues, and one missed step seems to derail the whole adventure. I've also had questions about how to modify tables, line height, and other basic styling within TinyMCE.

I think it might also be worth describing how pages are stored in MODX. I've had to describe that there aren't any physical files on the server that contain the pages you see; it's all stored in a database, so you can't just modify files "the old fashioned way." So far, my clients pick up the idea quickly, but it's generally a new concept for them.

OK, here's a start. Below is a download link for version 0.1 of the MODX content management guide, a Microsoft Word document designed to be adapted and handed out to system end-users.

http://shorewalker.com/downloads/modx-content-management-guide.docx

The audience for the guide

This guide is for the people who use MODX Revolution to update and add content on existing websites.

These people are not developers or designers. They have titles like "communications officer" and "marketing manager" and "personal assistant".

These people do not need to write templates or add snippets.They generally just need to add text and photos and the like.

Making life easy for these people is crucial for any designer or developer handing over a website to a client or to non-development staff. Make life easy for these people, and you'll get more work, both with that client and through great word-of-mouth.

These people need instructions on how to use CSS styles, on why pasting straight out of MS Word is bad, on how to take shortcuts by duplicating existing pages, on how to publish a document, and much more.

How the guide works

It's a Microsoft Word document.

Why Word? Because Steve Ballmer has personally bribed me with an enormous sum of money to put it in this format. So there's no point arguing about it. (Actually, that's a lie. Word is very widely distributed, many people know how to use it, and it has lots of useful features. But you can't say that.)

The document relies heavily on Word styles and fields. You should be able to change a few custom fields in the Document Properties, change the fonts, replace the logo, cut out the bits you don't want, PDF it, and send it to the client right away.

To change the fonts, you just need to change two styles: "Body Text" for all the body copy, and "Display Roman" for the headings and such. (For what it's worth, the document was originally set up for use with the Franklin Gothic font. The line spacing is slightly out when I change it to Arial.)

Those changes should take you 15 minutes, tops. (Hint: You probably don't want the section titled "Send email alerts and newsletters"; that's the EmailResource material.) The layout should adjust to everything you do.

Let me know in the MODX forum (http://forums.modx.com/thread/?thread=78207) or at http://shorewalker.com/about.html if you find Word's document properties or styles too obscure to do what you want, or if the document has some obvious layout flaw that's stuffing you around. No-one has ever previously encountered such a problem in the long and storied history of Word, but you might be the first.

What's in the guide?

Not enough.

This is an early release. It assumes that the designer or developer has not made any form customisations to the interface. It assumes that the system is running TinyMCE. It probably assumes other things I can't think of right now.

The eventual aim is to include downloadable, updatable screenshot packages that can be tailored to an individual's set-up. How far we'll get with that, I don't know.

Purely because I needed it, the system has details of how to work with Bob Ray's EmailResource add-on, which simplifies the creation of newsletters from MODX content.

Next priorities

Priorities for improvement include explaining how to:

• Add documents such as PDFs
• Add simple tables

Help improve this

This guide is based on feedback from forum users and the separate work of Valeska Scholl and Verango Media on similar guides for MODX Evolution users. More feedback is essential.

For the moment, it's probably best to keep this as a conversation on the MODX forums. Go here:
http://forums.modx.com/thread/?thread=78207

If you have a chunk of Word material you want to send me, my contact details are available at shorewalker.com/about.html and on page two of the document itself. [ed. note: shorewalker last edited this post 11 years, 3 months ago.]

Looking at this (in LibreOffice) gives me an idea! I got permission some time ago to "port" the SitePoint book "HTML5 and CSS3 for the Real World" to MODx. It uses a rather boring dummy newspaper page for its working tutorial. But using it to actually port this to HTML5 would be a lot more fun! Can I, please?

Quote from: sottwell at Jan 08, 2013, 05:32 AM

Looking at this (in LibreOffice) gives me an idea! I got permission some time ago to "port" the SitePoint book "HTML5 and CSS3 for the Real World" to MODx. It uses a rather boring dummy newspaper page for its working tutorial. But using it to actually port this to HTML5 would be a lot more fun! Can I, please?

Go for your life!

Fun!!! http://sottwell.com/content-management-guide/

Of course, this is just a beginning. I'll work on it as I get the time.

Since this has been updated and more versions added, I've taken this old one off of my site. [ed. note: sottwell last edited this post 10 years, 1 month ago.]

Ok, mostly finished, except for the chapter on email. Some adjustments to the original, as there were some errors and omissions. http://sottwell.com/content-management-guide/ [ed. note: sottwell last edited this post 10 years, 1 month ago.]

Great work. I've always had to write half-baked documents as quickly as possible and they always confuse clients .

It would be nice if it was supported in some sort of official capacity. Something like a git repository where everyone can contribute to an open format. Just an idea.

Quote from: sottwell at Apr 09, 2013, 08:30 AM

Ok, mostly finished, except for the chapter on email. Some adjustments to the original, as there were some errors and omissions. http://sottwell.com/content-management-guide/

Susan, if you have a list of changes (or better still, edits to the original Word document) I'd very much appreciate seeing it so that I could update my version.

I will take a day to go through it again, this time adding comments, and I'll send you my commented version. There is a slight problem in that the document's layout is not quite what it ought to be, since I'm using LibreOffice instead of Word. For some reason, on page 7, it starts embedding two columns into each of the page's main two columns, resulting in the appearance of four narrow columns on the page. I haven't been able to figure out why or how to fix it. But then I'm not really a word processor user.Figured it out; it apparently sees nested sections that all are set for two-columns, so all I had to do was re-set the excess sections to single-column, and it all comes out right. I don't know if this is from the original Word formatting, or if LO just made some not-quite-correct assumptions. [ed. note: sottwell last edited this post 11 years ago.]