Improving the MODX Documentation

General
1

At the MODX Meetup in Amsterdam last week, I gave a talk about an ongoing initiative to improve the MODX documentation.

The slides can be found here: https://www.slideshare.net/hamstramark1/improving-the-modx-documentation-march-29-2019

The primary premise of that talk is that everyone should be able of helping out with the new documentation. It’s based on markdown files stored in github, with support for different version branches (2.x, 3.x) as well as multiple languages.

Most coordination around this effort happens on Slack, in the #documentation channel, which I’d like to invite everyone to join. Discrete tasks and to dos are also listed in the Docs repository (for work that needs to be done on the content) and DocsApp repository (for work that needs to be done on the application/site that serves the documentation).

As not everyone is on Slack, I figured I’d open this topic for questions/ideas about the initiative as well.

Most important links:

The slides from my talk include a bit more information on the why/how of this initiative.

10 Likes
2

As a brand new user of MODX, I’m excited to see improvements to the documentation.

With experts writing articles, it can be hard to breakdown processes to a level where beginners are able to comprehend. Would feedback on the documentations ease-of-use/understanding be helpful?

1 Like
3

Absolutely!

Any documentation that fails to clearly explain its concept to beginners should be updated, but the people that already know how something works may not notice the problem. So 100%, please do report such feedback. :slight_smile:

4

The Revolution extras have now also been imported and can be seen at MODX Extras | MODX Documentation

I’ve tried to update the list of recommended extras on that index page as objectively as possible, but I do have my own biases, so would really love some feedback on that new list. :wink:

Ivan Bochkarev has done a great job at cleaning up most syntax from the conversion, but there are a few pages that need more work too, where help would be much appreciated. Some are logged at GitHub · Where software is built but also please report issues if any other pages look broken.

2 Likes
5

Well me also a beginner to MODX,and after listening to reviews and seeing the manifesto,i m too excited for new features of the same…Hopefully will not be disappointed.

1 Like
6

Absolutely, that has always been my biggest frustration with the documentation. People say the instructions are “very straightforward” but when you read them they are almost incomprehensible.

What would make a real difference is lots of screenshots and if possible video or screencasts of what’s being done. IE Worked examples.

The other issue I find is that many instructions jump straight into more advanced uses or start with a complicated use, when what we really want is to understand the basics first. Take it step by step. First baby steps, and then progress from there.

The third issue I have is that many extras don’t have any instructions other than “Install thru the manager and your good to go” Whaaaat?

And one final point, many of us are not coders or programmers; we may be designers, business owners, marketers or artists.

So technical orientated language is indecipherable to us. Doesn’t mean we’re not smart, it just means we think different and do things differently. So again video and sceenshots are really useful.

:grinning:

1 Like
7

I hear you and fully agree :wink:

Please log issues in the Docs tracker on GitHub when you have a “Whaaat?” moment so specific pages that jump the gun can be addressed.

Can’t promise I’ll do much in terms of videos myself, but screenshots typically are within my grasp. :slight_smile:

1 Like
8

When I first started with MODX I wasn’t a developer and I remember one of my biggest grievances with the documentation was the overwhelming amount.

I recall just wanting to put a class on the navigation and I had to read through a dissertation of documentation on wayfinder just to figure out how to do that. Luckily I didn’t have the luxury of walking away from MODX as my employer insisted on it, but I would have walked away due to the lack of straight forward practical documentation.

Now, fully understanding it, I would say it’s straight forward and all the information is there. However, it’s probably still incredibly frustrating for newcomers who just want to ‘stick a class in there’ or something simple.

4 Likes
9

I might have missed this – is there a plan to tag content in the docs that is intended for beginners/not-beginners/devs/etc?

10

Exactly,

I’ve just been thru that with Formit as some of you know (Thanks).

I’m a long time Modx user since Evo days, and I like to think I know how to use Modx pretty well (for a non coder) but I couldn’t make head nor tale of the Formit Documentation.

I learned from reading some 8 year old tutes around the web and asking endless questions in this new Forum. (Big thanks to all of you who put up with me and helped.)

The point is the documentation for Formit is 8 years old. Even the doc in the new section is just a copy of the older doc.

I think my recent various threads on it would make the good basis of a new tute and documentation.

I know putting together decent documentation takes time, but if Modx is serious about marketing itself to a wider audience then there needs to be a serious strategy to get the documentation . And that of course means setting aside a budget for it.

:heart_eyes::star_struck::sunglasses:

OK, I just read MarkH’s slides, and have some real concerns.

There’s talk of using Github, Markdown and Slack.

Say what? :flushed:

OK, I know what they are, but people who are not technical will not go near those things.

My eyes glazed over just looking at the slides.

So I worry that the process is already going down the geekspeak path, and likely to make the same mistakes with indecipherable docs all over again.

I also notice in the calls for people to help there’s not a single mention for professional communicators or educators. - writers, teachers, speakers, advertisers, marketers, technical writers, document writers, editors, pr, sales people etc.

I’d really recommend getting a professional communications advisor on board before going any further, otherwise the new docs will be like deja vue all over again. :blush:

Sorry if that all sounds a little harsh, I don’t mean it to be, but it seems like you’re looking at the problem from inside the bottle.

You may need to hire an outside person to provide perspective and really make the new docs project work.

:eye::eyes:

11

This is a community run project with zero funding. I appreciate your comments, but your proposal of hiring anyone for this is simply not founded in any sort of reality.

Instead my goal with the talk was to encourage everyone to pitch in and work on it, together. Your recent formit experience is an excellent example where you can help: reflect on that and pinpoint where the formit docs failed you and how it should be written to prevent others from going through the same process you did.

12

There are no plans for literally tagging like that, but the new top level structure does split it up that way (getting started = beginners, building sites is a little more in depth, extending modx is total nerd for people like me)

13

MarkH, yeah I get there’s no funding, and as i said, i didn’t want it to sound harsh, just wanted to put a few things out there that i saw as some possible gotchas going forward.

:blush:

14

It’s not a harsh tone I’m worried about. It’s this implication that anyone is getting paid for this work and that there’s money to go around to hire professional writers, and that apparently the project is doomed without hiring professional writers.

That last part is what frustrates me more than anything - I’m convinced we only need the people we already have to step up and help out just a little bit to create a massive impact. Most of the work done so far was done by around 5 people; imagine how much easier we could make learning MODX if just 50 people would pitch in to help improve one or two pages that they struggled with? 50 people, for comparison, is only 1/3rd of the people that took a few days out of their schedule to travel to Amsterdam for a meetup.

That’s my end-goal here, to get people enthusiastic and empower them with an open and transparent process, and turn that into meaningful improvements that benefit everyone.

So, let’s talk about that.

You balked at the mentions of github, markdown, and slack.

Why?

What can I do to get you on board with the editing process we’ve put in place that is meant to be as open, transparent, and with as low barriers as possible.

The slides already show how you can use just the GitHub UI to make changes to the documentation, without needing to have any technical know-how, without using git. Markdown is a simple text format, the very same one you can use for formatting on this forum.

Should I do a super detailed writeup of the exact steps to edit the documentation? Or maybe do a 2-3 minute screencast showing the process instead? Would that help you to help the community or are we already doomed?

(For the record, you don’t need to join Slack to help improve the docs. It’s just a convenient place to discuss the initiative in real-time and to coordinate larger efforts on the application, design, etc. I literally created this topic as an alternative to Slack as I know that not everyone is or wants to be on Slack. Plus, these forums are a lot more pleasant to use than the old ones.)

2 Likes
15

I have to say, this is a huge step forward for the docs (using Github + Markdown for actual proper VC of the text? Game changer positive for us.) And it’s pretty typical these days for software to either use Github for their documentation, or something like readme.io / Confluence. So the negative tone on this is … I don’t know, it feels really off to me, these are normal terms to be using for this kind of thing.

1 Like
16

Very nice job on the Extras list and the page. My only suggestions would be:

SPForm under forms. SPForm is particularly good for beginners because it essentially creates an instant, spam-proof contact form that works out of the box. Kind of the opposite of FormIt. :wink:

MyComponent under Development Tools (or distributing your own extra).

NewsPublisher, UpgradeMODX, SiteCheck, and GoRevo are also fairly popular, but I’m not sure where they would go or if they should make the cut.

17

So I ended up doing a quick demonstration screencast of how editing the documentation works without using any git; just the browser and GitHub:

(I added subtitles cause I can sometimes speak a bit unclear; translations are welcome too.)

4 Likes
18

The new docs system is absolutely brilliant. It’s going to be so much easier keeping everything up to date now. I’ll jump in and make some edits soon.
Congrats to everyone involved!

2 Likes
19

A new design is ready for testing, with special thanks to @christianseel. Check it out: MODX Documentation | MODX Documentation

21
211527×802 172 KB

6 Likes
20

I’m not sure what you’re suggesting here? Where are these folks coming from? If they are a part of the MODX Community there is nothing to stop them from contributing and I know for a fact technical writers and documentation writers know how to use version control in 2019. We’re not going to have random members of the public magically volunteer their time to help out the documentation of a slightly obscure open source CMS. Also, I’m unsure of what a professional communications advisor is, but it doesn’t sound like it is the right choice here. Documentation and instructional writing are very very different than other forms of writing.

But, there are enough people here with varied backgrounds in the MODX Community to improve the documentation through a combination of developing/using a style guide and soliciting user feedback to help improve each document and the overall organization of the docs. Many people in the MODX Community have experience in writing books, web content, documentation for clients, marketing and more.

As @markh pointed out, if even 50 people put in a bit of time to improve some pages, even just a little bit, the documentation would see significant improvement over time.

As a living document, it will always be able to see improvement.

1 Like