What would make the 096x documentation better?

What do you think is wrong with the 096x MODx documentation?

I have been looking over the existing documentation and most everything is covered to some degree. You may not agree, but the docs are not as bad as their reputation. I do find the way the docs are structured to be confusing and sometimes redundant. I think that breaking up the docs by user type is not working..there should only be one approach, this would keep all of the pertinent info in one topic. IMO the documentation should not cater to ’content editors’ or ’designers’ and only to general all purpose users. Leave the user specific stuff to how-to guides and keep the documentation focused on the application and not based on the user.

What do you think could be changed to make the doc better?

I don’t think that we should expect, or want, the MODx development team spending any effort or resources on the 096x documentation, they should concentrate on all things Revolution. Therefore, it is up to the community to contribute to improving the 096x documentation. Maybe we could start some community brainstorming to attempt to improve the documentation. Any ideas?

Here is an outline of how i think the docs could work better (edit: added existing documents to list):

• Installing, Updating and Migrating
  * What is MODx
  * Downloading
  * SVN
  * Installation
  * Upgrading
  * Moving Site
  * Taking it down for maintenance
• Getting Started
• Quick Reference
• The Manager
  * Terminology
  * The Manager
  * Editing Documents
  * The WYSIWYG Editor
• Templating System
  * Template Basics
  * Adding MODx Tags
  * Document Variables
  * Document Caching
  * Adding Snippets
  * Adding Chunks
• Chunks
• Template Variables
  * What are Template Variables
  * Creating a Template Variable
  * (at) Binding
  * Document-Specific Resource Fields
  * Document Variables
  * Widgets
  * What are Widgets
  * DataGrid Widget
  * Marquee Widget
  * Floater Widget
  * Ticker Widget
  * Viewport Widget
  * RichTextBox Widget
  * Hyperlink Widget
  * Misc. Widget
• Snippets
• Plug-ins
• Modules
  * How to create and run a module from within the Content Manager
  * Managing module dependencies
  * Setting up configuration parameters
  * Writing the module code
• User/Doc Permissions
  * Manager Users
  * Why Manager Users, Roles and Groups
  * Manager Roles And Groups
  * Web Users
  * Why Web Users and Groups
  * Web User Groups and Document Groups
  * Creating a Web User
• API Reference
  * DocumentParser Object
  * Document Object
  * DBAPI

Shane,

Thanks for posting this. This is a great idea. I’d love to see the community members pitch in and help build out the 0.9.6x documentation.

Interesting Shane, thanks!

I was thinking about something similar just this morning! However, mine was about guides for specific most used snippets and some short series on day to day usage of MODx. But I like the ideas you have put forward here, so I will keenly follow and hopefully contribute to this thread. 

To your list I could probably add "Chunks" ,"FAQs" and/or "Quick Reference"

Cheers/k

kongondo : I added Chunks and merged Quick Reference with Getting Started (i think that they are close almost the same thing, or am I mistaken?)

FAQ is a good idea. Just wondering if this should be a Documentation topic..I guess it is OK to be in the docs.

The more informative and comprehensive the Documentation and User Guide can be the better. I think an FAQ is a great Appendix for a user guide. Many people have the same questions etc. This is a huge resource and while we have FAQ’s on the public wiki a singular resource will be most helpful.

For developer:
Don’t you think we need to make a standard form of making-utilizing-modifying of 3rd party add-ons?

eg:
- coding standard
- phpdoc style
- installment (through copy-paste, select ’system configuration’, or like modx’s (or AFAIK the most current modx’s TinyMCE update) auto-wizard?)

Yes, modx doesn’t want to bond people to use a strict path.
But as an Open Source, everybody should make a ’shakehand’ agreement about procedure.
Otherwise, the ’3rd party resources’ will not follow the progress of the core.
We do not have to create the new standard. We can just AGREE on using the existing one.
But consistently.

Shane,

Thx for the additions. By Quick Reference I meant some condensed version of how to do the most important things - for those who don’t have time to read the whole documentation and/or would like to see if MODx is for them. It could also contain links to additional resources. Getting Started sounds to me like the preparatory stuff - logging in, additional configurations, etc. I feel like I am confusing myself, ha! Anyway, am sure there are experts out there who will chip in.

/k

Shane, great idea...

1) I think a quickie would be to fix the search function, it is kind of horrible now... that would help a lot when finding information

2) I think that the current info is fine for starting... a person maybe has to read it twice and play a little with MODx to fully understand it better

3) A set of snippet guides like Kondongo´s wayfinder guide would be awesome... available in pdf and html versions

4) I think the community effort should be in the Wiki... each of us has a set of bookmarks that kinda work as a personal wiki just in case we need some material for reference. And sometimes is daunting to go and read a thread in the forums with 200-300 posts and find just a few gems buried in all of that, so it would be wonderful that the community would distill all that info and pour it summarized and condensed into the wiki for all to have as a reference. This would make a great time savings, great reference and great documentation that would complement the current docs.

Shane,

Great breakdown.  Definitely a structure like you propose would be a great way to organize the information.  I would say the Quick Reference needs to be separate, for quick access, with links to more detailed information.

Maybe add a Recipes section, where people can add tutorials on making particular types of websites/functionality?

I think separating it like you’ve laid it out would be great. Right now it’s really scattered and can be hard to reference.

mary

Lots of great points here.

The MODx Documentation and User Contributed Tutorials, and How-tos should be in two distinct locations. The official documentation can be viewed as the MODx core. People are welcome to make suggestions or submit changes (until being invited to the Documentation Team). The Wiki can be viewed as user contributed addons to the main documentation where anyone can post tutorials and how-tos using the MediaWiki format. Anyone who wants to go ahead and start working on the Wiki addint tutorials and maintaining current documents please go for it!