Documentation concerns (rtfm, modx extras, placeholder listings, getPage, breadcrumbs...)

Hello. I apologise if this isn't the most appropriate place to ask this.

I also apologise in advance for what might be interpretted as a rant, of sorts. I LOVE MODx, it's beautiful, so I only want this to be interpretted either as the questions of a 'noob', or the suggestions of a patriot

I've been a bit concerned about documentation for Revo of late. Much of my concern was eliminated upon discovering rtfm.modx.com, as it clearly contains quite a bit of useful information about MODx and it's various extras.

Two kinds of concern remain, however. The first relates to searching for documentation. It seems to me that the rtfm site isn't 'google-able'. Searching for things like "modx revo getpage" to find the parameters and placeholders for something as fundamental as the getPage snippet resulted in absolutely nothing useful, so I wonder if either I'm being a bit dim or if somebody else has noticed that it's not possible to use a normal search engine to dig up Revo documentation.

The second concern, also relating to my getPage example: having found and used the getPage information I can't help wondering if it is complete, as I'm sure much of the documentation is not. For example, at the bottom (http://rtfm.modx.com/display/ADDON/getPage) there are examples of the page nav templates. But it doesn't seem clear whether I'm supposed to assume that these example templates are intended to serve as a definitive 'listing' of all the page nav related placeholders provided by getPage. If it turns out there are other placeholders that haven't been used in these basic page nav examples, I'm not sure where I'd go next to get the full listing.

It might be worth adding here that I also worry that there isn't a dedicated section for Revo extras, to separate them from Evo equivalents. For example, it took me quite a long time to find any kind of documentation for Breadcrumbs. Of course now I know where to look, but getting to rtfm is quite a chore in and of itself if you don't memorise the URL. So having discovered the page on Breadcrumbs it's clear that there's no distinction between the Evo and Revo editions. Should there turn out to be differences I'll have no way to know.

Finally, and in addition, it concerns me that there's no explicit link to documentation from the "Extras" page for a given extra. It's easier to find the Breadcrumbs page in the extras section of the modx.com (http://modx.com/extras/package/breadcrumbs) than it is to find the documentation for it (Evo version, I believe) on rtfm. It boggles me that there isn't a link to rtfm from the most common extras.

Thanks for reading. I want to be useful, rather than a pain, so please let me know if I'm way off base.

Googling: MODX revolution (not revo) documentation componentName has always worked for me (using no quotes):

works fine.

The documentation of any Open Source project is always incomplete and often out-of-date. Remember that you can ask for permission to edit the docs once you work things out so that the next person won't have the trouble that you did.

If you run into trouble, asking on the Forums will usually get you a fairly timely answer. If you then mention the problem with the docs, it will usually be corrected fairly soon.

If there's anything missing, there's a comma where it shouldn't be or you simply don't understand the documentation (meaning it is unclear): http://bugs.modx.com/projects/docs/issues File it!

And I usually just look for "modx getpage". The first two results are from the RTFM (getPage and the part of using getPage with getResources) and then there's a couple of links to forum topics... seems searchable enough to me, no?

I would second adding a dedicated "Documentation" field to the extras though of course it's up to the developer (and the rest of the community..!) to create docs or not, and how in depth they are... but everyone can help.

Often, there is a link to the documentation in the readme.txt file, which you can see by clicking on the + sign next to the package in Package Manager.

davidsmith is onto a great idea here with his suggestion for a documentation link on each extras page. I've found myself looking for this several times.

The documentation page linked from the relevant extras page should also clearly show users how they can contribute to the documentation, since even new users can quickly become expert in the usage and quirks of a particular extra.

MODX is so powerful that the absence of more thorough documentation quickly becomes pressing. A lot of the good advice is buried in the forums.

Oh, and everyone buy BobRay's book, which will provide a lot of the answers: http://modx.com/about/blog/modx:-the-official-guide-available-for-pre-order/ [ed. note: shorewalker last edited this post 12 years, 7 months ago.]

+1 for a documentation link on the extras page.

I know devs are sometimes strapped for time but it would be great to have a minimum docs requirement as part of the package submission process. Just a simple list of the params available and a few example snippet calls would save a lot of headaches.