I find Percussion’s documentation better than most (maybe I haven’t seen enough to compare), but a style that could be called Documentation 2.0 would help. That is, if you know the official term for something, and if Percussion uses it the same way you do, you will probably find what you need. But if, for example, you don’t know that you need to create a “Relationship” or if you have a question about the relationship between two entities that doesn’t involve the “Relationship Engine,” you’ll have more trouble. It would help to have a documentation indexing system that involves synonyms, even technically incorrect ones, and that includes other uses for official terms. That’s one reason some of us turn to the forums so often - it provides more of a folksonomy rather than a taxonomy.
Michael,
We’ve actually been having some internal discussions about alternative ways to deliver Rhythmyx documentation to take advantage of Web 2.0. One specific option we’re evaluating is delivering at least a portion of Rhythmyx documentation via wiki, which is a method I’ve seen a few organizations using. We may have an initial release of one or two “documents” via wiki around the winter holidays.
BTW, the term “Documentation 2.0” has been kicked around a bit by a few people in the technical communication community, so the idea is definitely out there.
Please continue this discussion. We’d like to hear about the options you’d like to see us consider, and about the concerns that Web 2.0 delivery might raise for you as well.
RLJII
I think a Wiki would be an excellent idea for Rhythmyx documentation, especially as it can be updated in real time, thus providing the most up-to-date information. It could incorporate many of the useful Forum threads too.
I would support setting up a Wiki for Rhythmyx developers i.e. the same user base as the Forum.
Cara
That’s one of the biggest advantages of a wiki over a forum - the current version can reflect “current best practices.” If it’s properly maintained and edited, it can be also more readable - it can look like real documentation. But at least a wiki can eliminate the problem of “these four forum posts were a rabbit trail, because it turns out the only possible working solution was posted on another thread the next week, but it only works if you also make the change specified in yet a third thread.”
Having a section for example code would be really neat as well (ie. php.net has the code just similar to forum posts, but it would be nice to have a section devoted to useful snippets of code that perhaps percussion starts / builds the framework for but in the end the end users could maintain / add / improve it etc.)
Anything that provides easily accessible, often maintained documentation is a good thing in my book.
One of the biggest frustrations I’ve had trying to figure out things while working in Rhythmyx is that there doesn’t seem to be a really good single source of answers; there’s the documentation PDFs, the help in the Content Explorer, the help in the workbench, various questions (but not always answers) scattered around the forums. Frequently I end up coming to the forums and asking something that I’m sure I should be able to find somewhere, or that someone else must have asked before, but my efforts just aren’t turning up an answer.
A wiki, as a single regularly updated source of documentation that’s easy to navigate through, sounds like a fabulous approach to tackling this.
Jit, there was briefly a Code Snippets forum here, but maybe it wasn’t the right venue or format. I like the posts at php.net - “This is how to use (or avoid using) this function in the real world.” It would be good if Percussion could build the framework for this.