A note to authors about guides for their software...

[awgie]

As I browse this site, and I have done so for a couple years now, I am still amazed at the number of video tools that do not include user's guides with them. This applies mainly to the freeware tools, as that is what I generally search for.

I have been doing video editing for 20+ years. I have worked with software costing thousands of dollars, but I find the freeware tools work quite well for almost all of my needs these days. I can figure out most software with my eyes closed. There are, however, a lot of newbies who just don't have a clue what they're doing.

You, the authors, would know better than anyone how to use your creations. If you can create the software itself, it seems to me that creating a manual would be comparitively easy. I see comments from newbies who have tried a piece of software, but couldn't figure it out, and couldn't find a guide, so they went on to something different. Do you really want users to toss off your software simply because you didn't take the time to write a simple user's guide?

So, as a programmer AND a user, I beg you, please include a user's guide with your software.

[guns1inger]

Not news, but anyway.

FWIW, most programmers I have known have a very poor grasp of the English language, and are even worse when it comes to English as it is writ (this has nothing at all to do with outsourcing, I am talking about people born and raised in English speaking countries). The same holds for writers in other languages.

This is why software companies employ technical writers.

I have read many of the guides here, and the quality is very varied. From the well written to the well meaning, what it really shows is that some people can write guides, and write them well, and some people can barely scrawl their name on the page, even though they write great software.

[CogoSWSDS]

For what it's worth, I grew up in the U.S. English is my first language. I am a programmer - that's my day job. I don't write documentation well. That's not where my talents lie. I can write good software, but documentation and guides are not my forte.

I have a BS. degree in Engineering. I tried to get out of taking composition in college, but didn't pass the test that would have let me get out of it (it was a pass/fail test). My academic advisor said that it is typical for engineers to not do well in writing. So I second what Guns1inger said, that most programmers don't have a good grasp of the written English language, when it comes to writing it. We can read and understand it just fine, just not the writing part... Goes with the territory I guess. I'd much rather show someone how to use the software I created than document it - it's easier!

CogoSWSDS

[FulciLives]

Well I understand what awgie is saying.

I don't expect a step-by-step "user guide" but I do expect a brief explanation of certain "features" or "settings" and what they do or don't do and at least a "hint" at when they should be checkmarked or not checkmarked etc.

Ever read the "manual" for CCE SP? That is a good example. It explains each settings in such a way that it isn't a guide per se but you understand what they do. For instance ---> This setting should be set to 'X' for a PAL source or a progressive NTSC source but if you have interlaced NTSC source then set this setting to 'Y' instead of 'X'

That explains the function without being a guide that tells you how to differenciate between PAL and NTSC and the different versions of NTSC but if you know all that then at least this "setting" isn't mind boggling.

Does that make sense?

Too often I've seen settings in software that are for ... what? ... I don't know!

- John "FulciLives" Coleman

[guns1inger]

Agreed - the software should have tool tips and a help file (even a pdf) with a field by field description.

But the help file should be proof read by at least two other people, and the content of the tool tips need to be included in any test plan written for the testing of the software prior to release.

[awgie]

For what it's worth, I grew up in the U.S. English is my first language. I am a programmer - that's my day job. I don't write documentation well. That's not where my talents lie. I can write good software, but documentation and guides are not my forte.

...

I'd much rather show someone how to use the software I created than document it - it's easier!

CogoSWSDS

I certainly understand what you're saying. I built by myself a two-story set for a theatre production, and was asked for written instructions for correctly and safely disassembling it. I would much rather show them how to do it than put it in writing. They are definitely two different processes. I can write well, but documenting instructions is not my favourite thing to do, and I certainly wouldn't consider it my forte, either.

Anything would be better than nothing - a brief stroll through each of the menus and options just telling what they do, i.e. what will happen if they are checked/unchecked. It doesn't need to be written as a doctoral thesis; it just has to be understandable to the inexperienced and unlearned.

Take it to the waitress at the diner and ask her if it makes sense. Show it to a coworker (who isn't a programmer) and see if they can understand it.

[filmboss80]

Hey, I'm just grateful to see that so much great freeware is being developed. I used to pay mucho bucks for the capabilities a lot of these tools offer. So let's pat the developers on the back. There are a lot of good searchable tips out there already; someone just may want to compile the info into user-friendly guides. Awgie-- any specific software guides you want to see written? Not that I'M volunteering or anything. (I'm a busy fart.)

[Bjs]

This is why you employ somebody who is IT Cert III qualified, and let them do the work ... like myself, lol.

[usually_quiet]

I often wish for more documentation when using freeware programs, but I understand why it is often insufficient or entirely absent.

Much of the freeware we have is written in one person's spare time, and writing good documentation can be almost as much work as writing the program. Also, it isn't desirable for the people who write the code to test the product or write the user documentation for it. In both cases the programmers are too familiar with their own work to do a good job.

Designing the user interface correctly is often the most difficult task a programmer faces. Connecting the various windows logically, and building each of them in accordance with a familiar standard, say the one for Windows, requires a lot of time. If it's done correctly, using the program seems intuitive. The opportunity to make mistakes is reduced, and there is less need to refer to documentation, but programmers often think they've done a better job at this than is actually the case.

Tool tip help and context-sensitive help are a good idea, since it seems like about half the users won't ever bother read the manual, even when it is well-written and well-organized. Unfortunately they are a lot of work to program. Left to their own devices, programmers seem about as interested in doing that as they are in writing adequate comments for their code.

[awgie]

filmboss80, I agree with you. As I mentioned I used to use software that cost thousands of dollars, but now these free programs are just as, if not more, powerful. Their creators have my undying admiration.

I don't need the guides so much for me, although once in a while I do need to figure out what certain options are for, or why something suddenly has stopped working the way it should. And it does take some semblance of effort to keep up with technology today.

Perhaps the authors could get some ideas for generating guides from others who have already done so.

For example, DivXMediaBuilder includes .CHM help files with their software. And ImgBurn has a support forum which has one entire thread dedicated to a line-by-line breakdown of each menu item and every option in every dialogue box. Their support forum can be reached directly from the help menu in the GUI.

These are just two examples of software developers who have done a great job and gone to a superb effort in creating help files for their users. And ImgBurn's support forum provides an excellent interface for users from newbies all the way to experienced users like me to read the FAQ's or ask questions and get an answer fairly quickly right from the program's creator.

[videopoo]

awgie

Just a thought.....I assume you do this work for a living? I think it might be smart business sense not to allow certain folks access to the knowledge you have. You can figure this out but others will not - thats why you make the big bucks!

Honestly though....there's not much on the freeware side of things that can match up to tools like After Effects, Final Cut Pro or Premier for example. Decent freeware for DVD authoring is non - existent. Yeah...there's lots of free tools that can be helpful, but for MOST of the core video work, it be silly to use freeware tools.

[redwudz]

Sorry, this isn't latest video news. Our Programming Forum may be a better choice. Moving you.

[awgie]

Yeah, redwudz, as the thread progressed, I saw that, too. Thanks for the move.

And no, videopoo, I actually don't do this for a living. But I'm somewhat flattered that you would think so. It's just a hobby of mine. Fifteen years ago, I did do video work for a living - cameras, editing and authoring. And I agree, for the actual authoring, I haven't found much in the freeware world that measures up. But for minor editing and video conversion, there are a number of good freeware choices, depending on what you want, and how much control you want to have.

[Nilfennasion]

I have to voice my agreement in some ways. Freeware is often difficult to come to grips with, and it is only through the guides written on Videohelp that I was able to figure out how to copy my DVDs reliably.

I am the opposite extreme. I used to write things that got published in home theatre magazines, and have manuscripts for three complete novels sitting on my hard drive. Although I have been a bit slack with my writing in recent years, stringing together a sentence is easier than toasting bread for me. The exact opposite is true of programming. I tried to program the Commodore 64 and Amiga many many moons ago, but never got beyond the basic step of writing PRINT statements. Even getting the programs to ask for input was too much for me.

What does not help, and while this is not about documentation it may be relevant, is when programmers leave out vital functions from their programs. The iDVD and iMovie combination is sweet as for making your own DVDs, except it will not let you input chapter stops at specific points in your movies. What makes it funny is that Steve Jobs apparently said its okay because nobody will be using DVD or discs in five years. Even if that were true, I would like to know where we can get the time machine he apparently rides on so I can go to a time where not being able to place a chapter at 6:11 as opposed to "every 5 minutes" is not a monstrous inconvenience.

[tin2tin]

The idea of a freeware developer as a software company, who should provide everything from a to z is wrong. The developer is not benefiting like a company would on their product(but hey, what about donationware? - let's be honorst about it - is a joke). The real benefiters on freeware are the users. And in that sense I really don't understand why contributing to freeware in any way is such a difficult thing for users. Personally I spend almost 4 years on DVD slideshow GUI mainly with users who wants me to do something for them(the actual user contributions in that period are a french translation and 4 jpg backgrounds and a lot of bug reports, for which I'm thankful, but I hope you get my point).

It may sound like a cliché, but the first question shouldn't be what developers should do for their freeware, but you(as users) can do for freeware...?

Well, another question in this discussion could be, if users of freeware actually are reading the docs. Sometimes you get the feeling that just because people are getting it for free, they think they should be able to do anything in it, without any time used on figuring out how the software actually works.

Decent freeware for DVD authoring is non - existent.

I disagree on this. Borax's Gui for dvdauthor/Muxman is a very decent(actually great) piece of software, with a lot of work put into the docs... But it's not getting the reconition (I think) it deserves. Is the reason for this that you actually have to read the docs to use it's (very advanced) features? Talk is cheap. So a more speciffic question to you guys could be: How would you in words/images/videos give fellow users a better change to benefit from free software like Gui for dvdauthor?

(And yes, english is not my first language, I did not spellcheck this message and I really, really dislike writing docs. Actually is the reason for me coding to avoid writing. I'm a filmmaker struggling with the script for my next film and when my writers block hit the hardest, I code.)

[Nelson37]

Usually_Quiet touched on it, but I want to amplify this point.

The people who write the software know it backwards and forwards. They have made great efforts to provide menus and interfaces to access the features. It's like asking a carpenter to explain how to use a hammer, they tend to look at it and wonder "just what is it that's not immediately obvious?"

I do a lot of PC training and work well live, verbally. When I can see the audience and/or listener, I can tell when they are not understanding something or don't get the underlying ideas. When I try to write things down, I either gloss over too much or spend too much time giving detailed explanations of things which are, or should be, already understood.

Having read a great number of commercially-written instructions for software, I have found very few that are really worth the paper they are written on or the time it takes to read them. There's just too much ground to cover. You almost have to use the software, experiment a bit, and research for in-depth answers on specific points.

Particularly in the case of freeware, I think it is up to us, the user community, to write the User Guides.

Anybody remember the "Guide" that basically went "get some video, encode it, burn it to disk, and there you are!"

[awgie]

tin2tin, to address your questions...

First, what can users do for freeware? That is a very good question. I have read some user-submitted guides here on videohelp.com that were very informative and would definitely help other users learn to operate the product, and I have read some others written by users who not only didn't know how to use the software, but also didn't know much at all about the process they were attempting. Now, a decent user's guide can't fix a user's not knowing what they are trying to do, so that's not what we're asking. But if a user does know what they're doing and understands the software, and if they can write good documentation, then they could and should submit a guide. That's why that option is available.

Second, are users of freeware actually reading the docs? I can't speak for anyone but myself, but yes, I do read them - rather thoroughly, thanks for asking. Any user who thinks that a single program can do anything would be considered a fool. Just as if one would expect a vacuum cleaner to brew a pot of tea. You bring up the GUI for dvdauthor, and while I don't agree with your opinion that it is a great piece of software, this discussion is not about our opinions on specific programs. The documentation for the GUI as well as the documentation for dvdauthor itself are both fairly extensive and easy to understand, considering their advanced subject matter, so their creators are not the intended audience for this thread.

Third, you ask how would we, the users, in words/images/videos, give fellow users a better chance to benefit from free software? (I'll omit your reference here to GUI for dvdauthor, since it is already well documented) I for one would be only too happy to write a user's guide for newbies, if it were for a program that I actually use, and if the developers would take just a little time and write a technical guide. There are still some settings, with the pace of technology, that I could not explain without doing some research first.

You have implied that you write scripts. Do you not, when writing a script for someone else to use, give a brief description of each of the characters in the production? It can take months, even years, to write a good script, and only a few days or even hours to write the character synopsis. An actor or director may not be able to write a script, but when they are reading one, that brief character synopsis gives them a little insight into why that character has just said something unexpected on page 112.

In the same way, a user's guide - even a poorly worded and highly technical one - gives the user some insight into why their screen has just gone blank, or why they've received an error message they weren't expecting (as if there could be an error they were expecting).

[tin2tin]

Well, I'm pretty sure that you won't find any developer, who doesn't want good docs on their software, and who wouldn't want to help you out, if you would write docs/guides. The reasons for lack of good docs have allready been touched above, and that developer wanting to keep his knowings a secret isn't one of them.

Basically you can see freeware as a gift, but asking for more after recieving a gift is a bit... you know...

So the only solution I can see is changing the 'I want...' mindset to a 'how can I help...?' attitude instead.

(Sidetracking here: The creative process in filmmaking is not really comparable to using a tool on a computer. I'm a filmdirector and a script for me is not a manual, but something I want actors to go explore in and develop their parts from, like a stepping stone. A good script contains questions you need to explore instead of just doing (totally uninspired) what's written. )

[AlanHK]

a Decent freeware for DVD authoring is non - existent. Yeah...there's lots of free tools that can be helpful, but for MOST of the core video work, it be silly to use freeware tools.

Rubbish.
The DVDs I make in GfD look as good and often work better than most mid-range "professionally made" DVDs. The blockbusters of course are far more elaborate (though truthfully, who would not rather just a "Play" button immediately than minutes of graphics, promos and warnings?).

Unless by "author" you are thinking of video editing.

[AlanHK]

The people who write the software know it backwards and forwards. They have made great efforts to provide menus and interfaces to access the features. It's like asking a carpenter to explain how to use a hammer, they tend to look at it and wonder "just what is it that's not immediately obvious?"

Probably the easiest and best way for software writer who finds creating a guide a challenge is to take a few example tasks and walk through the steps he would take, preferably with some screenshots.

I used to wrestle with Unix manual entries. When you're trying to use an unfamiliar application, having a dry list of options and terse explanations is really little help in grasping the rationale of the program. Usually I'd read the man page, try to do something, fail, read the man page again, realise why some heretofore mysterious options were important, try again. Repeat several times, each time getting a little further.

The few rare manual entries that added illustrative examples were much, much easier to grasp.
You can step through the examples, looking up each command for details.

[filmboss80]

When I expressed my gratitude (an earlier post) for so much great freeware, GUI for DVDAuthor was one of those I had in mind. It's capabilities are phenomenal for a free tool. Take it from someone who was in on the early days of DVD authoring. Tools with GfD's capabilities once cost thousands of dollars. The only thing missing from GfD is the ability to burn to DLT. Whenever someone needs help with GfD, Borax is quick to respond. Bless him, I say. And bless the makers of Audacity and ImgBurn and VirtualDub and AVIDemux and DVDFab and the Xvid codec, etc., etc., etc. And what can I say about this website? I've been a film/video producer for more years than I want to admit, and I'm always looking for ways to be more resourceful whenever I get a tight-budget project. I've made it a hobby to integrate pro applications with consumer apps, to see how much I could accomplish with a slashed budget. I discovered this site many years ago, but did not join the forum until '07. Young video knaves that I have mentored sometimes tried to complain that they didn't have the money for great video apps, and I always gave advice from what I saw on this site. To shut the mouths of the complainers, I built a video workstation that used about 80% freeware (I still pay bucks for a good timeline editor), just to show what can be done. I also point my teenage kids to this site, as they like to make YouTube videos. And so, to everyone here, I thank you.

[gadgetguy]

There's a difference between a "User Guide" and a "Reference Manual" but the difference is often blurred when it comes to documentation, both commercial and freeware. A Reference Manual should identify all of the functions and controls and what they're for. A User Guide should show how to use the functions and controls to accomplish a task. But very few tasks require using all of the functions and controls that may be available in a given application. IMO programmers should write Reference Manuals for their application, either in a comprehensive document, help file, or even just the tooltips as long as it's done for every control. Leave the User Guides for someone else to write.

Having said that, developers of freeware applications are under no obligation and should not be expected to offer any documentation or support. In most cases the application was written to sate a curiosity or address a specific need that the developer had. Going the extra step and cleaning it up enough to offer it to others that may find it useful is above and beyond the call. And those that go even further and provide help, updates, additional features, etc., are gods among men. These people are only to be applauded. There's nothing wrong with asking for enhancements or docs, but there should be no expectation that the author should make such changes or provide such documents, and if the authors chooses not to implement your suggestions, it should not be held against them.

[awgie]

(Sidetracking here: The creative process in filmmaking is not really comparable to using a tool on a computer. I'm a filmdirector and a script for me is not a manual, but something I want actors to go explore in and develop their parts from, like a stepping stone. A good script contains questions you need to explore instead of just doing (totally uninspired) what's written. )

I agree, and yet disagree.

I find everything in life comparable to using tools on a computer. Building a set for a stage production is like authoring a DVD. The video, audio, subtitles, still images, and menu structures are all the raw materials for your DVD, just like boards, fasteners, canvas, and ropes are all materials used for building the set. In the case of filmmaking, I agree that the script is not the manual. The script is more like the program, and the actors are the settings and functions of that program. The director is the user, and he watches the way each of his actors gets on with each other, and he may need to go in and tweak one or two of them if he is not pleased with what he sees. But without having that character synopsis from the author, the director has less information to go on in deciding whether the actor is within the character's intended scope. Obviously there is more to a character than what can fit in a single paragraph, just as there is more to a setting in a program than can be described in a simple manual.

That being said, I do agree with you that there is a lot more to acting and directing than there is to a computer program. A good director will push his actors to explore their characters, and to become their characters. Speilberg said, "You cannot act your character, you have to BE your character." The director will push them to the edge, but not let them fall off. That is why there are re-writers on the set of a film production. As the actors become their characters and make them their own, sometimes the script needs to be changed. When I see a group of actors really interacting well together, I have to wonder how much of it was scripted, and how much was ad-libbed.

[FulciLives]

There's a difference between a "User Guide" and a "Reference Manual" but the difference is often blurred when it comes to documentation, both commercial and freeware. A Reference Manual should identify all of the functions and controls and what they're for. A User Guide should show how to use the functions and controls to accomplish a task. But very few tasks require using all of the functions and controls that may be available in a given application. IMO programmers should write Reference Manuals for their application, either in a comprehensive document, help file, or even just the tooltips as long as it's done for every control. Leave the User Guides for someone else to write.

I guess that is what I meant earlier ... a "Reference Manual" ... plus Pop Up Tool Tips are nice as well

- John "FulciLives" Coleman