MODX Documentation Improvements and Expansion

A number of folks on Twitter had a discussion yesterday (also Skype chats and Emails) about maintaining and improving the documentation, filling the gaps and making it easier for people to learn and build a depth of understanding with MODX.

Here’s a summary of the suggested goals:

• Make it less developer oriented (what does this mean?).
• Include more examples of solutions using particular pieces of MODX
• Provide better pathways for non-developers to grab hold of concepts.
• Get more people involved in writing, editing and generally contributing.
• Keep the documentation up to date, matching the state of the Releases and potentially in lock step with development where possible.
• Build a Documentation Team in the community to actively improve and expand

Note about this Discussion: I’d like to see this thread as a positive discussion on how to achieve these things, how we at MODX can help, if there are any tools or initiatives we should consider like "Doc Sprints" or "Documentation Partys" or "Sponorships" or Document/Area Adoption. Please steer clear of rhetoric or complaint. Please offer your ideas, examples and wants in a concrete form; the more detailed the better. If you see a doc that needs work and don’t have the knowledge to correct it, please file a Feature Request in http://bugs.modx.com/projects/docs/issues and it will be addressed.

Technical Note: We will not be moving off Confluence in the short term (although we will soon have it incorporated properly with our SSO) and therefore there are technical limitations to how we can structure our docs currently but we are considering other options.

Special thanks to @gallenkamp, @bridgecourt, @einsteinsboi, @billy_koch, @mark_hamstra and @sepiariver (Twitter handles) for their interest in starting this discussion.

I suggested this in another thread and still stand by it:

When a extra is submitted it must be submitted with ( lets say ) decent instructions on the use of it ( for example 5 examples for different ways to use it ), that could then be added into a forum for testing by volunteers who only have access to that forum ( I’m more than willing to do tests on a development server ), the MODX team could set out a series of tests and the testers would follow them, if it passes the tests then it gets accepted to the package manager, if it doesn’t it gets passed back to the developer with the errors which they can then fix and re submit it, once passed the testers would update the wiki with the instructions ready for when the package is available.

I beleive that covers 2, 3, 4, 5 and 6 of what you want to discuss

First, we should define what "documentation" means for each us. I am user, but also admin and sometimes developer. These are three different approaches to look at our beloved MODX. I will get back to this as soon as I arrive at my gf’s place

Thanks to smashingred for getting this on the road!

Guido / @gallenkamp

@paulp,

While I don’t disagree that add-on and extras devs should write helpful documentation but many of them build them while working in their business and turn them over to the community for free. We test them to ensure they work but this is outside of the basic scope of this discussion. Here we are talking about MODX Revolution, Evolution and Core/Sponsored Addons.

I think we need to define what comprises "decent". "I know it when I see it" springs to mind. As a non-dev who has worked with modx since 2006 I don’t really need much instruction since I understand how to use most paramaters so long as they are defined to others they want a whole tutorial with demos and examples for a large number of scenarios usually really wanting their specific use-case fully explained.

With regard to volunteers, while we have some amazing folks here in the MODX community we have a small community of active participants, we’re working on ways to reward folks who help out but such a committee of reviewers is long in the view. If there are people here in this thread willing to step up and commit and therefore prove me wrong, by all means lets go for it.

Thanks Jay for getting this going. When I think of decent documentation it means that I should be able to follow instructions (even if I don’t fully understand the technical code behind them) and (without it assuming I know to do things that are not written in the doc) it should work and function.

I find myself (as a non-dev/coder) trying to make things happen by lots of trial and error. For example the documentation on Quip. I basically gave up on trying to get this to work. As someone who doesn’t get into code very often the documentation did me no good. This is not meant to be negative, just sharing where we might be able to improve.

So I guess we could isolate 3 things: the intended "reader" (website admin, developer), the level of skill needed (beginner, intermediate, pro) and the purpose of the doc (a how-to on a subject, ways to do things etc.).

I agree that it’s up to the developers of a plugin to provide good documentation and the main focus should be on MODX itself and the core plugins needed to make the main uses happen.

My 2 cents.

While I don’t disagree that add-on and extras devs should write helpful documentation but many of them build them while working in their business and turn them over to the community for free. We test them to ensure they work but this is outside of the basic scope of this discussion. Here we are talking about MODX Revolution, Evolution and Core/Sponsored Addons.

It’s on the developers hand if he can provide a documentation or not. Or it’s your problem. That said I hope you understand what I now trying to explain:
A developer codes a extension with MODX best practices. This is a very very hard work. If it works, it’s fine for him. At least he want to share this to the community for free(!!!), so he offers it to modx.com.
As he is not paid you cannot treat him to provide a proper documentation.

I’m not a developer but I try to do my best improving docs for MODX addons. I translate, I write docs, I make a MODX User Group. All for free. It’s just to feel better myself by sharing this. So I think you should really provide useful improvement requests to the bugtracker and hopefully there is someone who can do this. If not, you have to pay for personal support. It’s like that, isn’t it?

Finally, come to User groups, file bug reports, try to improve docs by yourself

Great points. That is the advantage (community) and disadvantage (offered for free) of open source apps like MODX. We definitely should all be contributing as much as possible, especially those of us who make a living with MODX as one of our main tools. I really do try to pitch in and make vids, help on Twitter etc.

Maybe we just need more of a standard for how the docs get written and presented. So that anyone can jump in and make the docs better but all follow the same guidelines. More consistency which will make reading multiple docs easier.

Quote from: bridgecourt at Jun 16, 2011, 08:02 PM

Maybe we just need more of a standard for how the docs get written and presented. So that anyone can jump in and make the docs better but all follow the same guidelines. More consistency which will make reading multiple docs easier.

That’s a great point.

I may be biased as a MODX developer with enough knowledge about how everything in the systems work to be able of using a simple table with properties to find out what the exact name of that limit property was - or was it depth? I’ve been helping out with the docs for a while but that is stuff that I do in spare time (or time that I can’t put myself to work - which, as I’m a freelancer/company owner, is spare time to me) and I can’t dedicate a certain number of hours per week to it.. it’s just whenever it goes.


Now I personally feel that the quality of documentation is on a good enough level to be a reference. With reference I mean that when you have the general perception, general idea, all you need is a nudge in the right direction. Being the name of a property, a definition of an access control or just on what tab you can find what.

I guess that’s the reason it is perceived as sucky mostly. People without this "frame of reference" don’t know what to do with certain things, or how to achieve a certain goal. Heck, something as simple as a "parameter" or "property" can lead people new to the system wondering what to do.

Perhaps that’s where the term documentation should be introduced. Something that, like Crawford said,
Quote from: bridgecourt at Jun 16, 2011, 07:23 PM

... means that I should be able to follow instructions (even if I don’t fully understand the technical code behind them) and (without it assuming I know to do things that are not written in the doc) it should work and function.

Step by step, holding hands on every turn and most importantly: copy/paste & working. Aimed, perhaps, at someone who never used MODX before.


But then again, some parts of the documentation require two totally different documentation pieces: end-user manuals and development documentation.

Quote from: novolo at Jun 16, 2011, 08:03 PM

Quote from: bridgecourt at Jun 16, 2011, 08:02 PM

Maybe we just need more of a standard for how the docs get written and presented. So that anyone can jump in and make the docs better but all follow the same guidelines. More consistency which will make reading multiple docs easier.

That’s a great point.

But no one will write them, that’s the point so lets get the developers to write a few examples and then pass it over to a testing team that will write them. Look at the last few years, no one ever complains about MODX, in fact I only ever hear praise about it and I defend it to the hilt in my company, however the biggest complaint is the docs are not upto the standard of other CMS like wordpress, why do you think thats done so well, its not because of having no docs to refer to.......

I’m not knocking MODX or the developers cus there very talented, god I’d love to be able to code like Jason and Shaun, but the negative attitude about getting the developer to write a few example usages of the add-on is daft, were not asking for god / gold just a starting point.

When I first started working with MODX and was researching addons for stuff I wanted / usage I got so annoyed by descriptions and the lac of docs so lets do something about it !!!!!!