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.
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?
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 8 years, 4 months ago.]