MODX Documentation Improvements and Expansion

This is an excellent discussion and while it might get a bit testy it’s really needed. Mark is right that we all come from different backgrounds. This really goes beyond documentation and to the heart of MODX itself. Do we (and the team at MODX) want Joe (who has no knowledge of the internet other than Facebook and email), the owner of Joe’s tire shop to be able to use MODX to easily set up and manage a site for his business? If the answer is yes then there is a lot to work to do because right now that’s not possible.

The next level is just as valid. Is MODX aimed at the graphic designers, web designers who are pretty savvy with the internet in general but have NO idea how to put together a snippet call and add parameters? If the answer is yes then we still have a lot of work to do. MODX documentation (and maybe MODX itself) is aimed at developers or casual coders who can wad through and get stuff done. I know that’s a generalization and doesn’t apply to everything in MODX but it’s mostly true and Mark confirmed it exactly.

I myself am in the middle. I honestly don’t want to spend time looking at code. But I do what I need to help my client. For anything custom I just ask MArk. and other great devs in the community.

So how do we take MODX to the masses? Better documentation is a start.

@paulp,

It would be nice if addon developers would write detailed docs for addons but as I said the process flow is typically this: Developer is working on a project that is putting food on their table; Developer things well this would be handy to share with other folks; Developer abstracts the code a bit if possible and shares it.

Some devs write docs because they know the value of the docs is almost equal to the addon. We can do a better job of asking people to document their work but in my experience working with Open Source software/communities for almost 20 years I don’t see this changing without an ernest effort from volunteers who use and can write the documentation.

We cannot require devs to provide documentation because if we did that we’d miss out on some brilliant and simple addons that work well. A system for reporting addons that need more docs or a team of reviewers to watch new addons as they come in to adopt the project of addons doc improvement would be another option.

the biggest complaint is the docs are not up to the standard of other CMS like wordpress

This is obviously the case, it’s why we started this thread. (I don’t agree with your comparison.

, why do you think thats done so well, its not because of having no docs to refer to......

It is not its docs it is because it is a consumer product that has market driven demand for development not because they had hot docs. The WP Codex was once quite a cobwebby spot, in fact people like Lorelle on WP started their own site to educate people on WP until she was finally made head of documentation.

I’d like to bring this back round to concrete improvements and again, try to steer clear of complaints. I think the way Crawford described his wants is a perfect example of what he perceives as good documentation: Instructions.

Is MODX aimed at the graphic designers, web designers who are pretty savvy with the internet in general but have NO idea how to put together a snippet call and add parameters? If the answer is yes then we still have a lot of work to do.

I am hardly a coder and I took to MODX very quickly. In fact coming from hacking apart WP themes it was a fresh breath of air not having to mess w/ PHP and OPC (other peoples code) . We’ll always have lots of improvement but less than you think.

MODX documentation (and maybe MODX itself) is aimed at developers or casual coders who can wad through and get stuff done.

It isn’t aimed at developers but written by developers and therefore their awareness of need and depth are far different from a newb who maybe skipped a getting started guide or just installed for the first time or a front end developer. We’ve all known or know someone who is extremely brilliant in their field and does amazing things but talking to them puts you to sleep because they don’t think the way you do. Only those rare people who are able to create analogy and provide examples with a narrative as teachers do can bridge that gap. It starts with asking questions, putting the answers in your own words and sharing it with others.

as Modx have international community it is difficult for some of us to redact good docs in english when developp add-ons.

The core/add-on supported have really good manuals now but some name parameters are strange for me :

for example getressources use showhidden to get/unget ressources which are not show in menu , and by default it is false.

this name is wrong for me and need to read manual to understand what it mean in reality.
the good name will be ’showonlymenu’ and false by default (invert test)

last time i use it i have forgotten this parameter and must put debug to understand why i not getting my ressources ...
i need to read code of snippet sometimes to understand meaning of parameters .
So in fact if you don’t understand php it is difficult to use some snippets .

[Edit] hum take too long to write ...

i agree with you smashingred
i am coder and sometines it is difficult to write docs , in french it is easy (basic doc, parameters and examples) but in english more difficult for me and i ’m not the only one, for example developper of events2calendar eventscalendar2 has written good documentation but in russian .

So need others persons to complete , translate manual
and please more examples

Excuse me if I plagiarize someone’s comment in this post, I can’t quote everything I’m trying to write this fast LOL cause I’m in the middle of something else...

IMHO:

Docs should be produced like any other publication, with a clear organizational structure, consistent tone/formatting/style. From my modest experience that looks like: Publisher, Editor-In-Chief, Department Editors, Technical Advisors, Staff Writers (usually in charge of specific sections/topics), Contributors, etc AND a "Style Guide" of sorts.

Obviously MODX does not have something like this in place, and no funds to do all this hiring, so we look to the community to provide a substitution but right now there’s no organization. SO...

I propose we "assign" a community volunteer to "fill" these positions for EACH snippet that gets approved for the repository. This may sound like a lot, but one person does the job for all, or a whole bunch, of the snippets. For example:

Publisher » @modxcms (if that wasn’t obvious)
Editor-In-Chief » Similar to Head of Documentation for WP. This person does at least one review on EVERY piece of documentation to ensure it meets some minimum requirements (set out in the Guide - more on that later). This person (if not one of core team) may need compensation of some kind - nice little write-up on modx.com, maybe an honorarium, etc cuz it’s a MASSIVE job.
Department Editors » In charge of whole groups of snippets. Can be categorized like the repo itself: "Content" section, "Navigation" section, etc. They will review and proofread EVERY piece of documentation for their group of snippets, edit, make changes, add stuff, make sure it’s well written and easily understood. They should have a pretty good understanding of their snippets but MORE IMPORTANTLY know how to deliver information in a useful and easy to understand way. Depending on how many snippets they’re in charge of this could be a small endeavour to a really big one.
Technical Advisors » Experienced MODX developers that the Editors above can depend on for help with their group of snippets, and who are able to write the "first pass" of most snippets. For MODX I see this group AND "Staff Writers" kind of being one and the same because the first pass at docs MUST be written by someone who knows very well how it works, obviously. A snippet’s dev - if they cannot even come up with a "summary" or a first draft - should at the VERY LEAST be able to explain it to a Technical Advisor who will write the first draft. Then NOTHING gets passed into repository without someone writing something!! After that, the Editors get it in their queue and when they get to it, they make it more user-friendly, if required.
Contributors » Anyone and everyone who’s willing to help but they MUST have some direction from the Editors in order for the docs to be consistent with the Guide.

No matter how we do it the Docs need a lot of work, but without organizational structure it will be for naught because it will never be consistent. If we want to expand MODX’s market to progressively less technical people (Techie designers»Non-technical designers»Hobbyists»End Users) then how far we can reach down that chain has everything to do with the Docs (and the Manager UI).

Just my 2 cents

I was also thinking about aggregating links around the blogosphere directly into Official Docs or at least key areas of the forums (in the auto-generated support threads, for example)

I recently pitched the idea of accumalating FAQs into the docs, similar to the way Sencha has it on their docs. While easy to maintain or set up (some FAQs just provide deeplinks into the forum), it is a wealth of information and I had it open in a different tab on multiple occasions.

It’s a way to provide easy access to some of the pearls of these forums (cause really: there is some amazing content hidden in there if you know where to find it) but not really organized. Though I am willing to give up that organization for keeping a few pages updated with interesting or commonly asked questions.


I sort of like that structure sepiariver laid out, and of course I would be willing to hop in on that - most likely on the techy side of things.


I also think Arialia has a valid point - not all of hte documentation written is English and some of the most amazing addons come from the Chinese or Russian communities which only document (and market) their addons in their native tongue. There should be something put in place to bridge that gap. I personally vouch for English first - local languages second, though that’s easy to say from the Netherlands where most people also speak English anyway...

Quote from: paulp at Jun 16, 2011, 06:27 PM

When a extra is submitted it must be submitted with...

...functional code. code not breaking anything or doing other harm. period. I realy don’t want to sound or be arrogant, but if you _expect_ more from me (resp. force me to do more to be available via package managment) i will simply release my stuff to public domain on other places. Its not an privileg for my extras to be available via Package Manager, its a privileg for modx.com and its community to get my extra via Package Manager.

The problem is, that writing tutorials eats away my time.

But i know how important tutorials (aka howtos) are as i’m regularly reading them too.
But... time. And i know that there are people who can write better tutorials than i.

What else?

I can draw my thoughts based on experience down to one line:


Make it accessible.


Make documenting accessible.
Make modx.com accessible.
Encourage potential Contributors to contribute.
How? By making modx.com accessible.

I realy don’t want to login here, login there.
I want to have my ONE login with my ONE personal page with links to all the areas where i can contribute.
I want a link on the page of my extra to the wiki for that extra. I don’t want to login again anywhere. I allready did log into modx.com
I have so much questions in my head about modx, i dont want to be disturbed by questions about how modx.com works.

And i realy don’t want to hear that the dev is working on it.
What means "the dev"? Arn’t we are all "the dev" together?

MODx is community driven, isn’t it?

jm2c

Quote from: pureppl at Jun 16, 2011, 11:35 PM

The problem is, that writing tutorials eats away my time.

I know the feeling.

Which is why I’m paying a good friend of mine a couple bucks, a couple of drinks and perhaps even a cookie to write the non-technical part of documentation for an addon that I will be releasing soon.


Don’t get me wrong - I totally feel your sentiment there, and I’m not saying you should be paying someone to do that for you, but I think that there is still a hefty chunk of responsibility for the devs to at least provide a head start that can be expanded on by others.

Maybe if we make some sort of template the developer has to fill out before submitting the plugin and having a group of people review the plugin and the documentation before releasing it to the wild can help.

Think of it sort of like the Apple store where the plugin goes through an approval committee that can be compromised by devs, front end devs and day to day users that way if someone from the group doesn’t understand whats going on they can ask someone from the group who does and not leave the burden on the creator.

I think this would probably get the docs moving forward and help others understand the ins and out of MODx easier and faster.

There are some really great suggestions here and I think we are moving this forward to get something more concrete in place.

I agree with Jay on his take on the developers...

It would be nice if addon developers would write detailed docs for addons but as I said the process flow is typically this: Developer is working on a project that is putting food on their table; Developer thinks well this would be handy to share with other folks; Developer abstracts the code a bit if possible and shares it.

Sepia River is onto something and I think with a combination of Ben’s idea and a similar one I had earlier this could be a good start. I for one would be willing to contribute as an editor. I can’t contribute as a developer but I do have skills in training and writing and can take the core of a doc and make it more "readable". Adding things like screenshots, video etc. would help a lot too.

If I remember right Joomla has a similar idea like this with a Documentation team made up of community members. We would need to set out the document workflow a little more and build on what Sepiariver has started. Then find out who would be willing to contribute and build the team. We’d have to have reasonable timelines too. I can do some editing but couldn’t do 100 a week you know?

Getting a simple template as Ben suggests would maybe help some devs think about how they start the docs.

Also I do want to say that it’s not just about snippets, plugins etc. There MODX itself too.