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

I have an online manual set up for my clients. This is just for editing their site, not for anything involving any programming whatsoever. I add my clients into a custom table, and when they log in, a script will show pages that are specific to that client. So, most of the pages pertain to everybody, and are shown to all, and others are shown only to certain clients. I add a link to the online manual in the File menu of the MODX manager, and the site running the manual captures the referring website, and if that matches the URL in the data table for a client, it will automatically log them in. I also replaced the URL for "help" in the MODX system settings with the manual so that anyone who clicks a Help button will also be taken to the online manual (I had to make a script on the manaul site to strip out everything after the domain name that gets added by the Help button, though, to prevent 404 errors). So, you can take a look and see how it is coming along. I'm still adding stuff every week.

http://modxmanual.com

You can log in with user name "modx" and password "modxManual". Let me know what you think!

UPDATE: I set the site to log you in as a visitor if you go there from this forum. Cool, eh? [ed. note: rainbowtiger last edited this post 10 years, 4 months ago.]

Quote from: sottwell at Apr 16, 2013, 07:06 AM

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.

If you've made any additions, please send now as I'm about to release a slightly updated version.

No, I haven't done anything with this other than port it to HTML.

Quote from: rainbowtiger at Dec 11, 2013, 01:17 AM

I have an online manual set up for my clients ... I'm still adding stuff every week.

Rainbowtiger, are you willing to let me re-use (with attribution) some of the material from this document? (I'm thinking particularly of the VersionX material, which is very good, and the Gallery material, which addresses an add-on I've never used).

Quote from: shorewalker at Mar 10, 2014, 12:09 AM

Quote from: rainbowtiger at Dec 11, 2013, 01:17 AM

I have an online manual set up for my clients ... I'm still adding stuff every week.

Rainbowtiger, are you willing to let me re-use (with attribution) some of the material from this document? (I'm thinking particularly of the VersionX material, which is very good, and the Gallery material, which addresses an add-on I've never used).

Certainly. You can use whatever you want. Can you just grab what you need from the website?

Quote from: rainbowtiger at Mar 10, 2014, 12:13 AM

Quote from: shorewalker at Mar 10, 2014, 12:09 AM

Quote from: rainbowtiger at Dec 11, 2013, 01:17 AM

I have an online manual set up for my clients ... I'm still adding stuff every week.

Rainbowtiger, are you willing to let me re-use (with attribution) some of the material from this document? (I'm thinking particularly of the VersionX material, which is very good, and the Gallery material, which addresses an add-on I've never used).

Certainly. You can use whatever you want. Can you just grab what you need from the website?

Yes I can. Thanks a heap, Rainbowtiger.

Your work is a huge step towards having world-class end-user documentation for a world-class CMS.

How about a GitHub repo that's a MODX content manager / end user documentation project.

I imagine something with:
- All the content could be markdown making it easy to reformat & repurpose.
- GitHub Pages could be used to wrap the markdown content in a nice responsive interface.
- Print friendly style sheets for PDF generation.
- Individual's or agencies can fork and maintain their own versions of the base project tailored to suit their needs while submitting pull requests for everything that is generic enough to belong in the main repo.

We're probably all delivering some kind of training, documentation, or manual with websites that we deliver. Let's pool our resources and do it properly.

It also creates a new way for site creators who don't necessarily have the chops to contribute to the MODX source to contribute more.

We could built a proof of concept now and get content rolling after 2.3 goes pl.

Quote from: jonhas at Mar 10, 2014, 12:50 AM

How about a GitHub repo that's a MODX content manager / end user documentation project.

We could built a proof of concept now and get content rolling after 2.3 goes pl.

Jonathan, in theory this is a great idea. I have a few queries:

• Has this been done successfully in GitHub?
• Is there documentation on how to do this in GitHub?
• Is Markdown flexible and rich enough to do this?
• Is GitHub user-friendly enough that a decent number of potential contributors will set up accounts and use it?

So far, despite invitations, I'm not being overwhelmed with other people's contributions. Perhaps that would change if we put the document into a different infrastructure (though that's far from guaranteed).

It's worth a try. Does anyone want to take the lead in putting the existing version into GitHub?

I'd also be interested in ideas on why having it in MS Word is a deterrent to people.

I don't have Word, and I know that a lot of MODX developers and designers are Mac users. I haven't checked it lately, but when I worked with it in LibreOffice to port it to HTML it did not format well at all when importing the Word version into LibreOffice.

The developers of SimpleCart and pdoTools have a documentation project up that I've used when submitting English documentation for some of the pdoTools snippets. It is integrated with a github respository, and uses the .md files.

http://docs.modx.pro/en/
https://github.com/bezumkin/Docs

A new version of the manual is now available at:
http://shorewalker.com/site-building/modx/modx-end-user-manual.html

The biggest improvement is instructions for Mark Hamstra's essential VersionX, courtesy of the fine people at Snow Creative Services.

There's also a .odt version that pretty much works in my version of LibreOffice. Non-Word users rejoice!

Thanks to rainbowtiger for new instructions on using Mark Hamstra's wonderful VersionX.

Let me know what you think.