What do we need? A new approach to the MODX Documentation.

Hi there,

as I somehow promised (drunken at MODXpo!) to provide a new documentation system, I'd like to ask you for your Opinion. There are several great systems and examples for documentation around the world. Which ones do you like and which you dont? Why and wny not? Which features do you like? Which features do you need? Which would be nice?

As most of us will know RTFM, lets take this as a start.

From a users/ learners view: What do you miss?
From an editors view: what do you like / miss / want?

Please let me know if you are an editor or a person who provided a MODX package.

Cheers,

Guido

More sample code. Displaying an API function's definition is very nice, but then how do you use it? A good example of documentation with working samples that are actually useful is the basic MIGx documentation.

More tutorials on basic usage. For example, how do you simply link to pages between contexts?

Quote from: sottwell at Mar 14, 2013, 05:11 PM

More tutorials on basic usage.

Couldn't agree more.

More documentation in any form as to basic MODX usage will reduce support threads created on the forums. It's just a given.

Personally (and Guido knows this as we've spoken about it on twitter!) I feel that making the documentation accessible on any device is also a bonus, so the ability for it to be viewed on say a mobile device on the go is great.

Personally I love what JQM have done with there 1.3 docs, build it on there own framework! Great way to promote there own stuff!

Yes. Basic usage is what I miss, too. The first steps could be easier. And I miss exapmples from real sites.
So lets collect to get a good starting point

A few quick thoughts:

1. +1 for more practical tutorials or tutorials at all =D plus something like jsfiddle for modx, like a installation with all the tutorial code up and working (resetting itself every 10 minutes or so, because some people will abuse it pretty sure^^) and then a textarea which is linked (from frontend to backend) to the nice console extra for executing the code an generating the output =), like this, you could play around right in the docs

2. EDIT: Actually, commenting is alrady possible^^...but only for logged in users, so not for as many people as I think would be good/EDIT User comments (they can be initially hidden to not disturb what the user is primarily looking for) an doc-pages, so valuable finds during development (and using rtfm) could be added easily (think on github, but right in rtfm, commenting enabled if you're logged in with your modx account) to the comments and if useful can be added/included/merged into the actual documentation by an editor (creator of page or editor that "starred" that page, see next point)...or the hardcore version: a mini github right inside the rtfm to fork rtfm pages, change them, send a pull request and so on, but I think that's too complicated...better to do it as described in the following thought...

3. Easier access/login for people who want to contribute to the docs (I had to ask kevin personally for an account =D), I think there goes a lot of willingness to nowhere, when to comes to improve the docs, because as a "normal" user, you just CAN'T edit it...this time think on a wikipedia (this would be the reeeally open version) where everybody can change/improve a page, this could also be limited to people with a doceditor account (would be nice from a managing standpoint if you could just use your modx login and if you sign up for a doceditor account you get the permission for editing the docs, so if you're logged into the forums, you're also logged in to the rtfm...

From there we could have a mechanism to follow rtfm pages. 1. pages created by yourself and 2. pages you bookmarked/starred/watched/whatever. When somebody changes something on that page or makes a comment, you get an optional email notification, this would maybe improve the quality of the docs if they are maintained by a lot of people


and thanks anyway to keep your word on rebuilding the docs =D...I would be willingly to help with the UI, if needed... [ed. note: exside last edited this post 11 years, 1 month ago.]

My question aimed on the structure of the new documenataion system. So "more examples" is not my business (yet!)
But it lets me think of another question: why? Is it maybe a topic for the DS after all? Maybe we have to think about why there are not enough examples and tutorials. Maybe there are, but not known tho this central library of information. Maybe its a task of the DS to gather all these from the web or at least link to them. Like a function that says "Look, I found a tutorial for this: $url"

@exside: Yes please! I am not a frontend guy