Other Software > Developer's Corner

Style guidelines for how to structure helpfiles?

<< < (4/5) > >>

mouser:
iphigenie's points about not searchable is key -- you really cannot meaningfully use a screencast as a good reference manual.

a screencast is fantastic for letting you get a feel for the way the application works and how you might use it, or as a teaching tool, but for advanced users who need to locate some detailed information quickly they are no substitute for a good help manual.

you can also use a a help manual to rapidly familiarize yourself with the range and scope of an application and spot features that are relevant to you in a way that is impossible with screencasts.

i think they are complimentary, especially for advanced applications.

Paul Keith:
you really cannot meaningfully use a screencast as a good reference manual.
--- End quote ---

Lots of web services use blogs to make screencasts much more easily searchable.

The end point shouldn't be forgotten though: "complimentary" not inferior.

This is the biggest flaw I think with the replies here derailing screencasts.

Even if you try to be neutral, what many of you end up saying is that the traditional help documentation is superior because you can wade through a manual.

Emphasis on "you". Yet help documentation is about help - not help preference.

Even for advanced users, the flaw of many screencasts are that they are dealing with often basic subject matters. This is not so much the fault of screencasts but screencast makers. It is then unfair to say that a help file is superior when what you're basically saying is that an ideal help file is better than majority of screencasts.

Well of course it is. That's like comparing some cream of the crop apples with some rotten oranges. The inherent properties of video though can still apply to advanced topics - it just depends on how you want your advanced topics to be received.

Omitting this virtue is basically tantamount to admitting you don't want to even consider maximizing your help towards your users because you're advanced enough to not need it and you can afford to not go further.

Screencasts are important especially as video annotations improve. Even top professionals of other arts can learn from watching someone work or understand better if they see someone's movements in sequence or frame by frame. Just because text is older than video doesn't mean it's valid to stereotype against the latter. For a long time, people didn't respect or didn't implement images in their manuals and now images are accepted if not encouraged. Video should have this same respect too - especially - especially for helping a user

All help documentations are complimentary towards the application. None of these even texts can survive on their own even if they are easy to search for. We all need some form of clue whether it is the visual trail of the mouse, the keyword associated with search, the clearly written links/outline besides the texts - all these should be here to compliment the help, not give reasons to reduce it.

daddydave:
Even for advanced users, the flaw of many screencasts are that they are dealing with often basic subject matters. This is not so much the fault of screencasts but screencast makers. It is then unfair to say that a help file is superior when what you're basically saying is that an ideal help file is better than majority of screencasts.

Well of course it is. That's like comparing some cream of the crop apples with some rotten oranges. The inherent properties of video though can still apply to advanced topics - it just depends on how you want your advanced topics to be received.
-Paul Keith (July 09, 2010, 08:46 PM)
--- End quote ---

I can agree with this and was thinking along the same lines. There's a reason people don't RTFM and it's because there are a lot of crappy FMs. And likewise the reason people like me don't watch screencasts unless it is something fairly technical like LINQ or the Python programming language is, there are a lot of crappy screencasts.  The question I didn't ask, but worth asking, was "What are best practices for good screencasts?"  I do think making a good screencast takes more effort, planning, and rework than making a good help file, so you are very lucky when you find a good screencast, and there are some good ones out there, in particular some of the Microsoft ones.  And Microsoft is good about providing transcripts so that they in effect become searchable. I propose a new acronym: WTFSC (watch the fine screencast!)

Paul Keith:
I think transcripts are a great start.

Other flaws I see with screencasts currently is that most of them are on the web and not on a blog page or some other forms that are much more navigational than youtube. (and much more easily downloable)

That said, it's not easy. I think in order to have a fine screencast, just like in order to have a fine manual, a presenter should understand that they are not providing a replacement manual but like with images, they are providing the best help they can provide.

Help is the relative word here.

For most people if a screencast can make it easy for you to both play and not play it and skip to the thing you want, that itself should be a requirement. (Both because it speeds up the loading and because it makes it easy to refer back to a specific section.)

Finally a fine screencast is best used reactive and introductive.

People usually falling in the middle are willing to navigate text rather than video because they themselves probably don't fully know what they are wondering about.

Introduction screencasts are great because it makes it clearer to complete newbies. Reactive screencasts are great because the problem is deemed explainable but too confusing or scary to do step by step.

Example: creating a... troubleshoot help.

If the helper can show you exactly what type of potential screen and errors you may encounter and what moves you need to do, even if you face a different error, it's much less scarier. You're not only able to produce a better text documentation for yourself via jotting down notes but you could better anticipate which section is about to give you the most headache and what you could immediately do to circumvent that trouble instead of a text manual saying If so and so happens do this... If so and so happens do that.

It's also great for long texts that need a form of social proof i.e. ebook making tutorials or web site making tutorials. If someone can immediately warn you to switch to a different app and that this is enough for now and let's not mess with this service because it may hold you back on the next section - it's much easier (and quicker) to grasp where each piece form to achieve a process rather than have a manual say - Don't forget this or Why you should this.

davidqxo:
I liked Steeladept's list in Reply #6.

Much of what passes for Help these days (including screenshots) resembles a useless programming comment that merely echoes what you're already looking at, e.g.,
  i++ # increment the index

Two of the most useful help resources I've ever had the pleasure to use are the Permuted Keyword In Context (KWIC) index for the Unix manuals (can someone supply a link for this?) and the online PHP Manual.

Permuted KWIC indexes are SO much more useful than either regular indexes or searching.

Navigation

[0] Message Index

[#] Next page

[*] Previous page