SilverStripe

Help us help you and your users with user help

Posted by Brian Boyko on 15 June 2010

We're in the middle of re-writing our user help to be compatible with SilverStripe CMS 2.4.

Well written user help documentation helps us and other SilverStripe developers save time. Every question that customers can answer themselves using user help is a question that they don't have to ask the development team. For that reason, as we shift from 2.3 to 2.4, we'd like to get away from focusing on features and more towards explaining how to accomplish tasks - shifting from "what things are" to "how to get things done." It's a massive re-write that has us practically starting from scratch.

It seems appropriate at this point to mention our mantra, "Be More Human." What we want is a user help that human beings can use to find out how to accomplish what they'd like to do.

But we're worried about hitting a pitfall. That is, we're too close to SilverStripe CMS - we use it daily. And there are things that may seem obvious to us that may be too complex to the end-users.

Right now, the user documentation for 2.4 is about half-done. There's still a ways to go - we haven't produced screenshots or screen captures, we haven't "themed" the user help site (we use one of the SilverStripe defaults), and there are entire sections of the user help that are currently blank. We are nowhere near release. However, we're close enough to it that we can start soliciting feedback.

In addition to oversimplification (or undersimplification,) there might also be some things that completely elude us. And of course, no one is immune to complete errors.

So what we're doing is releasing an "alpha" version of our user documentation for the next couple of weeks. You can reach it at this website.

Each page on the "alpha" user help has comments enabled, so if you have a comment for a particular page, you can leave it there. We may not have time to reply to every one individually, but we will read every comment.

We'll be collecting comments until July 15th, at which point we'll pull the alpha user help and comments offline, and make edits to the final version of the documentation which incorporates your comments. When we finally release the "1.0" version of User Help for SilverStripe 2.4, we will have a much more effective and useful user help.

Here's what we're looking for:

• Frequent tasks that we have overlooked in our user help. We think we've got everything an end-user would reasonably be expected to do, but it never hurts to double-check.
• Any patch of text which is unclear, ambiguous, or insufficiently detailed. If it doesn't provide the information an end-user could use, it doesn't help the end user.
• Any patch of text which is over-detailed. If the end-user can't understand it, it's no help to the end-user either.
• Any awkward phrasing or improper grammar.
• Places where a screenshot would be very helpful in explaining the subject at hand, as well as information on where a video screencast would be useful. Since screencasts are time intensive to create, it is probably a better idea to limit them until only when necessary. We can't use screenshots submitted by the community in a final product, (as we don't want images in the user documentation to be a mishmash of browsers, modules, and operating systems), but we can reproduce screenshots which you upload to an image hosting service like imgur.com.

Here's what we can't use:

• Any documentation text snippets have to be compatible with Creative Commons CC-BY-SA 3.0, and require attribution. GNU-FDL documents just can't cut it. (In other words, if you upload material that we use verbatim in the final document, if you give us your name, we can give you credit, but we can't pay you, and we can't use any text that isn't released for us to use.)
• Documentation of modules not currently included in the user help.

For helping us out, we can't offer much except for a quick notice on a "Thank you" page of the documentation. However, the better the user help, the more time it will save answering questions from end users - and that helps all of us.

Comments will be closed July 15th.