New guy offers input on documentation

Hello everyone

After spending a lot of time reading the docs and forum messages I finally had to post my first message asking for help here http://modxcms.com/forums/index.php/topic,3565.120.html. I was eventually able to report a resolution to the problem and I then offered what I hope will be taken as constructive input at the end of my post before realizing I should extract it from there and start a separate topic in this forum instead.


What follows will make more sense if you read this post first http://modxcms.com/forums/index.php/topic,3565.msg38267.html#msg38267


I have spent many frustrating hours floundering about the interface or searching for answers in the forums. I have not posted until this problem stopped me cold because of the clearly expressed attitude that MODx is not for non-developers at this point. I expect that is the same reason that this problem with the documentation has gone unreported until now. Once someone solves a problem no one wants to appear stupid by pointing out that they had trouble with the instructions.

But darn it guys this has nothing to do with being an experienced developer. There are countless places in the documentation and forum messages I’ve read where you are told to go to a certain place but not told how to get there. No amount of experience will help you find something like that if you are working in software with which you are unfamiliar.

Three months after this post http://modxcms.com/forums/index.php/topic,3276.0.html reporting a glaring omission in the documentation the problem was not corrected and I had to go through the same pain that he did and only found the answer by searching the forum. I have a real hard time seeing any justification for that. It would have taken less time to fix the documentation than was spent by some of the developers responding to his post.

I know and completely agree that it is important that the developers spend their time working on the code but in the case described just above the time spent would have been minimal to solve a significant deficiency in the documentation.

I have looked at many Content Managers before settling on MODx because of it’s standards compliant modular framework. Nothing else is really an option for someone like me who basically didn’t pick any content manager until he finally found what he was looking for. Given that, I can’t keep quiet about these kinds of easily fixable problems that are needlessly causing untold numbers of wasted hours by the early adopters of this fine program.

florida_guy,

You’re exactly right about the state of documentation, and while I strongly agree with you, the reality is that at this stage of the project we’re unable to address the problem in a satisfactory way. While there are many people using modx, and making fantastic suggestions and creating cool things with it, the number of actual developers of the core code is rather small (basically 3 or 4 main code committers, with one guy doing the vast majority of the work lately). What that means is that the people who know the most about the code, simply don’t have bandwidth to document what they know because they’re working on writing code. There’s also the issue that the people who write code, aren’t necessarily the best people to document it. Those are two orthogonal skill sets very frequently.

The project really needs a dedicated documentation resource -- someone who collects all the bits of knowledge on the forums and organizes them in a way that people new to the project can easily access. There’s been some ad hoc efforts at this, but as you noted in your post, they have not been very successful. That’s not a slam on people who’ve been doing the work btw. What they’ve done has been really good, but without clear ownership of the documentation issue, I am afraid that complete up-to-date docs will be hard to come by.

I invite you, or anyone else who feels motivated, to take on this role. I think a strong concise set of documentation, that’s owned and overseen by a single person, would be a great boost to the developer community for modx. And the effort obviously would benefit the end users as well

Quote from: vbrilon at Jun 25, 2006, 01:55 PM

florida_guy,

I invite you, or anyone else who feels motivated, to take on this role. I think a strong concise set of documentation, that’s owned and overseen by a single person, would be a great boost to the developer community for modx.

I am spending a great deal of time figuring out how to do each little thing that I need to know to develop my site. I find it frustrating how time consuming it is to figure out very simple things like the two examples in my original post in this thread. At least until I get my first site launched I am not inclined to spend additional frustrating hours figuring out how to do things I don’t need to do just so I can document them.

When I was going through the tutorials I found many things that could have been worded more clearly. If there were a common place to report these issues... In other words if when I finally figured something out there were a place where I could go and say... Why didn’t you say it like this ".... ". Then each person as they figure something out could improve the documentation on the things they had to scratch and claw to accomplish.

We obviously can not expect our international developers to be able to document their contributions as clearly as if English were their native language and we obviously don’t want to discourage them from contributing.

If there were some organized way to contribute bits and pieces we would eventually get somewhere.

It would also be a great leap forward, if someone would manage the contents of these forums.
Information about a specific topic ("how do I set up this or that snippet...") are often cluttered about several forums and threads.
This task does not require a pro documentation-writer, but someone who cares for the forums, eliminates redundancies, changes/corrects titles, renames and moves threads to another forum and so forth.
Establishing a structure and logic which could make using the forums much more effective. One forum for each snippet, binding-method, module could be a starting point.

After my first install of modx over the weekend I ran into the same block when it comes to finding info on the various elements available and the documentation. Although the sample site which I installed gives a few examples of usage it leaves a bit to be desired... for web savvy users this is maybe not so much a problem but for a novice it would be a chore to find relevent help for a specific task.

I came up with an internal help system (only done for snippets so far) which provides snippet specific help from a "Usage Tips" tab in the snippet edit interface. When a snippet author posts a snippet, they would create a help file which holds all the usage and configuration data which then the end user can drop into their help folder and have the information available instantly without leaving the manager...

2 main benefits I’ve noticed so far:

1. Instantly switch from edit snippet to snippet help in the manager interface
2. The snippet authors info, usage tips, and documentation can be added to the help file and removed from the snippet itself. Removing the unneeded code from the snippet reduces the file size which = less bandwidth & less database size. Take the stock DropMenu for example, I removed 82 lines of code and shrunk the database size by 44.3 kb on just that one snippet. Space and bandwidth cost so this (or something similar) would reap benefits for all end users.

How it works:
The snippet developer starts a thread for their snippet (first post should probably be a sticky so new updates would be easy to find) and then creates a help file and attaches it to the post or provides a link to it.
For example:

snippet name: toplink
snippet help file: toplinkhelp.php.txt

The user would then copy the snippet code, install as usual and then copy the help file and rename it to "toplinkhelp.php" and upload it into the help folder. The manager then checks the help folder for the help file and if one is found the information appears in the Usage Tips tab for that specific snippet. All the authors info is shown at the bottom of the tab (see attached screenshot) and everyone is much happier

Sample help file:


What do you guys and gals think?

breezer, that’s fantastic! I think it’s an incredibly welcome addition. What I’d REALLY like to see is some form of unified file format that splits out things based on identifiers in the code or a rudimentary XML format. We’ve mentioned something like this for a long time and I’m glad someone has finally done something. Good work!

Isn’t this the perfect situation for a Wiki ?!?
Surely it would help in categorizing support arguments, a much better approach than searching the forums and reading threads!

Being a collaborative effort it would also stimulate contributions from users; one can write without feeling the pressure of being officially in charge for the documentation.

BTW I find the current ’Documentation’ section on the site pretty clear and well written; too bad it’s incomplete.

breezer, that really looks great and would hopefully help save time when people have questions about a snippet. Like Ryan said, if we can get a unified format for the files this would be a great addition.

I noticed you have a code view tab as well, is that something you are working on as well?

Yes, the help-tab is really useful. Right now, the documentation is a part of the snippet’s source. Awkward to read and use and eating up bandwith. But there might be a drawback: Since the snippet-code can be easily changed by the user (I tweaked DropMenu a bit) these changes are very likely to remain undocumented.

For practical in-depth instructions and examples a wiki could be the perfect solution. The forums don’t make it.
The main issue of documentation is not documenting the options for a specific snippet, but how to use all those modx features together in a site. When I had a place, where I could put in what I found out I would do it. Basically I solved all my initial newbie-problems in the meantime, but I bet there are a lot of other beginners out there who spent their precious time with the very same and solved, but undocumented problems - in fact they are all *wasting* their time!
I don’t post that stuff into the forums, fearing to make them even more confusing than they already are...

A place for users to submit methods and tips they use for various situations would be a bonus no doubt. Who better to write a how-to than actual real world users... the documentation team could then compile and refine the submittals to the appropriate documentation category.

To address the issue of documenting changes to snippets, there could be a place at the top of the snippet itself urging the user to document his or her changes. Still less bandwidth

kylej - yes, the help tab is just one of many alterations I am making. I have made quite a few modifications to my eto rc3 manager which I am now moving over to Modx - although most of them are already buit in. The code tab uses the geshi highlighter to show the code view which I have found invaluable in debugging snippets due primarily to the line numbers... if there is an error in the snippet you know right where to find it. (plus it looks cool too)

As to the unified file format, here is the code that produces the tab and calls the help files, any input to a better way is always welcomed...