Is the blog too long? Here's the summary.

All too often, people complain about the MODX documentation not being up to par, but far too little is being done about it. Even something as simple as reporting an error or missing information is vital – and something everyone can do. I'm going to challenge you to file 200 documentation bugs/request, and when we hit that milestone I will myself dedicate two full working days to fixing as many as I can.

What's wrong with the docs, and why does it matter?

Different people have different learning styles, and some need more handholding then others. There's also a ton of different aspects to MODX between the ins and outs of templating, the extensive API and on using the manager. Many of these are learned through trial and error, but not everyone has the time, resources or patience to learn then all. Documentation helps there. But in the past, developers have been far too busy to document it all – 2.2 marks a new era where most of new functionality was documented pre-launch – thanks guys!

That does leave a lot of older docs waiting for the same treatment though, and that's where you come in.

Found something wrong? Here's what you can do in 2 minutes.

  1. Go to bugs.modx.com/projects/docs/ and click the "New Issue" link in the left hand side or go straight to the new issue page. Note: you need to be logged in to the see the link in the left-hand side menu. If you don't see it, login with your MODX.com account (button in the top right).
  2. Fill in the form you see. Give it a descriptive title, and make it actionable. For example, "Login snippet does not mention placeholders for tpls" is much more useful then "Login docs flawed omg".
    The actionable part means it has to be specific enough that it can be executed in a reasonable time frame. While the system settings aren't all in the docs, making an issue titled "System Settings docs incomplete" (I think that's actually in the tracker right now) really doesn't make it high in (my) priority list. It lacks the part in me where I can see what the user was looking for, and I really can't just add all settings there.. that'd take me two entire days at least.
  3. Hit "submit" and go back to doing what you were doing.

If you file a problem with the docs that is actionable, it may take you a few minutes to write it up - but the odds are pretty big someone else will spend more time to address the issue. The result of that may save others hours of time searching for the right information in the future. Your two minutes can have a huge impact.

I would like to challenge the MODX Community.

The challenge is really simple.

We've got 14 open issues (40 total) in the docs bug tracker right now. Let's make that at last 200.

And then what? What do I get out of it?

When we hit the 200, that's a nice to-do list and I will personally dedicate two full working days to fix as many of them as possible. I may not be able to get them all done in that time, but I hope others will join this initiative and pledge to spend a portion of their time contributing to the docs. This effort will hopefully have a significant impact on the quality and completeness of the documentation, and will benefit a lot of people and of course the MODX Project.

What's the catch?

Nothing. While I've got a pretty broad knowledge of every area in MODX, a lot of people don't share in that knowledge and I don't see the flaws in the docs that newcomers do anymore, but I am able to explain it if asked. I believe that we as a community can make the docs better, and I'm backing it up with two entire days of work myself. In case you like to put a price tag on stuff, you could consider that a donation worth € 1 142,40 (or $USD 1,464.27) in labour (including taxes) to the community.

So, are you in?

What do you say? Are we going to make this work? Will you, from now on, file every issue (small or big) in the documentation, in order to reach that 200 issue threshold? Or are you going to pledge alongside myself to spend a certain amount of time on the docs when we do? Let me & the community in the comments, and share this challenge with people who work with MODX to get the ball rolling..

Get the conversation going, and post your thoughts in a reply.

Comments are closed :(

While I would prefer to keep comments open indefinitely, the amount of spam that old articles attract is becoming a strain to keep up with and I can't always answer questions about ancient blog postings. If you have valuable feedback or important questions, please feel free to get in touch.