Does Anyone Read The Documentation?

[rjcurrie]

Does anyone read the documentation provided with Hero Designer? Judging by the number of questions that are asked on this board that I know are answered in the documentation, I have a tendency to say no.

Sure, Dan and others (including me) are online often and answer questions when asked, but do you not think that we would prefer to be spending our time doing other things besides answering the same questions over and over again. Does it not make sense to check the documentation first and then ask the question if you can't find an answer?

Are people not reading the documentation because of problems with the documentation? Would people prefer a different format? Or other changes that would make the documentation easier to use? Creating documentation for a program with as many as options and features as Hero Designer is a lot of work -- work that I am reluctant to do if nobody is reading it.

But now is a good time to make suggestions for improvements to the documentation. It won't be long before I start work on the documentation for version 2 and if people want to see changes in style or format, the easiest time for me to add them is before I start to add specific version 2 changes. I am more than willing to listen to suggestions and if I think they will improve the documentation, incorporate them. I want the Hero Designer documentation to be useful -- if it isn't, then it becomes almost pointless to include it.

Now I understand that a lot of people don't like to read documentation. Heck, I don't and I write the stuff for a living. However, when I run into a problem with software, that's the first place I look to try and solve it.

Rod Currie
Author of Hero Designer Documentation

[Barton]

To improve the documentation add examples with screen shots. I find that this helps people use software more effectly.

[Killer Shrike]

I use the documentation as a reference. But, then, I dont ask many questions either......hmmmm. Perhaps there is a connection there ;)

[zornwil]

People don't read in general.

The documentation seems fine, I have consulted it with success on occassion. I'll admit as well I've asked a question or two (or more) addressed in it that I missed. I don't think there's anything you can do, Rod. It's good work, just human nature working against you. Also note of course you'll almost never hear when people do read it and find something.

[rjcurrie]

Originally posted by zornwil
Also note of course you'll almost never hear when people do read it and find something.

That's very true. It can just get a bit disheartening when I keep seeing questions that I know are answered in the docs. And as I mentioned, I have to wonder if there are reasons that people aren't using it and if I can address those in future versions. I write computer documentation for a living, but by no means, do I consider myself an expert in the field and there may always be better approaches than what I used.

On the other hand, I suppose I should be happy that no one has posted anything to the effect of "Hero Designer is a great program but the documentation sucks" (at least that I can remember; I may have blocked it out :)).

Rod

[rjcurrie]

Originally posted by Barton
To improve the documentation add examples with screen shots. I find that this helps people use software more effectly.

I'll try to add more specific examples (with more screenshots) in version 2, but I have to admit I'm a little reluctant to get into too many detailed examples and I simply cannot do it for every aspect of Hero Designer or the documentation will end up being 200 pages long.

Are there any specific areas of Hero Designer that people feel would benefit from more examples?

[RPMiller]

Originally posted by rjcurrie
I'll try to add more specific examples (with more screenshots) in version 2, but I have to admit I'm a little reluctant to get into too many detailed examples and I simply cannot do it for every aspect of Hero Designer or the documentation will end up being 200 pages long.

Are there any specific areas of Hero Designer that people feel would benefit from more examples? I think it would have to be the areas of template creation.
As a person that actually read the documentation after playing a little while (my usual MO), I found it quite satisfactory except when it came to the template design stuff, but a lot of that was because of all the fast changes that occurred.
Obviously, I am doing very well now ;), but it was a little rough in the beginning. I would like to see examples of code personally.
I would also be willing to write a section of creating RTF templates if anyone is interested, but you may have to bribe me to do so ;).

[rjcurrie]

I was waiting for someone to mention Template creation. That is, far and away, the weakest part of the documentation. My feeling is that it was good enough for version 1 and that I could update it in future versions. One of my goals for version 2 is to provide much more in the way of examples and information on creating and editing both character and export templates.

I'm really not sure that I want to get in the specific details of creating RTF export templates in the main documentation. Having worked with virtually hand-coding RTF in the past (actually, it was writing a program that converted files from UNIX's TROFF typesetting mark-up to RTF), I really don't think it's a task that anyone who isn't well-grounded in RTF should even attempt. However, that being said, if you were to provide me with even rough notes on the subject, I see no reason why we can't put together a document to be available from the web site for those who are interested in this more advanced topic. As for a bribe, I can't promise you anything. When it comes to Hero Designer, Dan is completely in charge of all bribery :).

Rod

[dbcowboy]

I haven't had much trouble with the software so I think I've only used the documentation once. However, I did find the answer to my question so it worked great. But you know Rod, I really do feel for you. Man, you slave away writing page after page of text and then Dan goes and makes the software so easy to use few people if any read and appreciate all the work you did.

So, I have come up with the solution to the problem of no one reading the documentation and I have to admit, once I thought about it, the answer was obvious. What's the most read topic on the Internet? Why, porn. All you have to do is add porn to the documentation and I can guarantee you that EVERYONE will read it. Why, you'll get people who've never heard of the Hero System or the term rpg used to in relation to the word role-playing scanning the document. I think the answer is obvious: porn, it's what's for dinner.

And I just want you to understand, I'm not trying to tell you how to do your job or anything, just offering some friendly advice because I care.

:D

(in all seriousness, documentation worked fine when I needed it, may scan it when I try a new function for the first time - I used it to understand how to export prefabs and I'm rolling along great with it, you guys did a great job on the whole package)

[rjcurrie]

Originally posted by dbcowboy
I haven't had much trouble with the software so I think I've only used the documentation once. However, I did find the answer to my question so it worked great.
Cool. Glad to hear it work for you.

But you know Rod, I really do feel for you. Man, you slave away writing page after page of text and then Dan goes and makes the software so easy to use few people if any read and appreciate all the work you did.
Techical writers only exist because programmers and software designers have yet to create an interface that is intuitive to everyone :). That being said, I don't see the profession going away anytime soon. :)

So, I have come up with the solution to the problem of no one reading the documentation and I have to admit, once I thought about it, the answer was obvious. What's the most read topic on the Internet? Why, porn. All you have to do is add porn to the documentation and I can guarantee you that EVERYONE will read it. Why, you'll get people who've never heard of the Hero System or the term rpg used to in relation to the word role-playing scanning the document. I think the answer is obvious: porn, it's what's for dinner.
Well, if Hero ever publishes Porn Hero, maybe I can get permission to use artwork from their to "enhance" the documentation. :)

(in all seriousness, documentation worked fine when I needed it, may scan it when I try a new function for the first time - I used it to understand how to export prefabs and I'm rolling along great with it, you guys did a great job on the whole package)
I think I can safely speak for Dan in this case and say thank you from both of us.

Rod

[Talon]

I read it...even though I didn't need to (having been on the beta). :)

The problem I have with the v1 documentation is that it wasn't updated as the export template taglist changed. I think the ideal solution for v2 would be some way for Dan and/or the program itself to auto-generate a list of all valid tags with some embedded help text, so that the doc supplement would literally write itself.

[Barton]

If the documentation with examples is too long, why not produce another how to use document.

The current documentation did not answer some of my questions, I actually had to use the software and play around with it to find out some features. A solid index to the documentation would be nice. A great index also indexes by how-to topics as well.

[misterdeath]

Docu-Ma-WHAT? What is this word, I do not think I've ever seen it before.

:D:D

Just kidding. I think the documentation is pretty clear. I've only had basic questions, and well, I too have been here pre-beta.

D

[rjcurrie]

An index is likely for version 2. It was primarily a time issue that one did not get included in version 1.

If you can remember what specific questions were not answered by the documentation, it would be useful for me to know.

Besides templates, which will be getting a thorough going over in version 2 anyway, what are the areas where people think more detailed examples would help? I have to admit, I'm having a hard time seeing what good they would do in most cases. Wouldn't they just end up repeating the same text with the general case replaced with the specific? For example, the general description of adding an advantage would say "Click on the Advantage you wish to add." while a specific example might say "Click on the Armor Piercing Advantage." Does that really tell you anything more?

[Vondy]

I have a few thoughts on this.

First, most studies indicate most computer users do not read documentation. Instead they try to intuitively work through a problem and if they can't they ask someone who knows the answer. If they can't ask someone who knows the answer they often return the product.

Second, while I, a technology professional, have no issues editing tags and playing with various templates and whatnot, most users are not. I see the answer: "edit the template" quite a bit. That's all well and good for a power user, but most users are not power users. If you expect people to edit templates the documentation has to contain clear instructions in laymens terms that take them through the step by step process. It should be clear enough that a monkey who can read basic english can follow it and enjoy success.

Third -- I absolutely loath electronic documentation if its in PDF format. Searchable HTML help rocks on the other hand. I want it in paper and I don't want to use hundreds of my own sheets of paper and the ink to print them with to get it. A booklet it what I want.

Just my two active points

[GreyGuardian]

The documentation was good. Glad you plan to improve it :).

Honestly I haven't had time to do more than a few characters with HD. I suspect a stress test might be happening in the next few weeks if I can find the time to write up some adventure ideas.

I also want to tinker around with the character sheet format to make something that is clear to my wife. Fortunately she has taught classes in instructional design so I'll make her do some work.

[Simon]

Originally posted by D-Man
I have a few thoughts on this.

First, most studies indicate most computer users do not read documentation. Instead they try to intuitively work through a problem and if they can't they ask someone who knows the answer. If they can't ask someone who knows the answer they often return the product.

Second, while I, a technology professional, have no issues editing tags and playing with various templates and whatnot, most users are not. I see the answer: "edit the template" quite a bit. That's all well and good for a power user, but most users are not power users. If you expect people to edit templates the documentation has to contain clear instructions in laymens terms that take them through the step by step process. It should be clear enough that a monkey who can read basic english can follow it and enjoy success.

Third -- I absolutely loath electronic documentation if its in PDF format. Searchable HTML help rocks on the other hand. I want it in paper and I don't want to use hundreds of my own sheets of paper and the ink to print them with to get it. A booklet it what I want.

Just my two active points
A note here: editing the template is used as an answer for folks that want to change the rules of the system. In my mind, that is a "power user".

The goal of HD was to create a chargen that implemented the rules of the Hero System. That is it's primary purpose in life.

As much as was possible in the time that I had for v1, I included the capability to customize it. Much of this customization (read: changing of the rules) requires template edits.

Is this something that I expect every user of HD to be able to do? Absolutely not. But if you're looking to make a chargen that follows (and enforces) your own special rules, you're going to have to be a bit more than a "layman".

That said, there will be numerous GUI-based rules screens in v2 which will take the place of many of the template edits that are currently necessary. Will editing the template still be necessary for some things? Absolutely. In general, I'm putting all of the "hard coded" rules into rules screens. If you can change something by creating a custom template, then it's not going to be included in the rules screen (at least, not at first). This is an attempt to keep the rules screens from becoming unworkable messes.

I think that in many cases, expectations need to be corrected. HD is a chargen for the Hero System. Nor your own personal modification of the Hero System, but the <i>Hero System</i>. As much as possible, it will allow for customization and house rules....but that is a secondary goal to following the rules as stated in FREd, the supplements, errata and FAQs. v1 hits the primary goal better than any other chargen on the market. v2 will begin to address the secondary goal of customization much more strongly.....

[rjcurrie]

Originally posted by D-Man
I have a few thoughts on this.

First, most studies indicate most computer users do not read documentation. Instead they try to intuitively work through a problem and if they can't they ask someone who knows the answer. If they can't ask someone who knows the answer they often return the product.

Not much I can really say to that except that I would think that looking in the documentation would come as a step before or after asking someone, especially for a group like Hero Gamers who one would suspect are quite capable of reading and looking up information in a document.



Second, while I, a technology professional, have no issues editing tags and playing with various templates and whatnot, most users are not. I see the answer: "edit the template" quite a bit. That's all well and good for a power user, but most users are not power users. If you expect people to edit templates the documentation has to contain clear instructions in laymens terms that take them through the step by step process. It should be clear enough that a monkey who can read basic english can follow it and enjoy success.

I can only go so far here in that the tools used for editting a text file are going to vary from platform to platform. And besides, it's not up to me to teach them how to use the tools that come with their computer. That being said, when I rewrite the sections on character and export templates for version 2, I will try to keep this in mind and make my descriptions of such steps as painless as I can. But until HD provides its own internal method of editing templates, there is little I can do.



Third -- I absolutely loath electronic documentation if its in PDF format. Searchable HTML help rocks on the other hand. I want it in paper and I don't want to use hundreds of my own sheets of paper and the ink to print them with to get it. A booklet it what I want.

Just my two active points

Well, that's really a personal preference. I despise documentation in HTML format and much prefer PDF because I have the option of actually printing off something that looks like a book. And PDFs are just as searchable as HTML, you simply click on the binoculars in the toolbar of Acrobat or Acrobat Reader, select Find from the Edit Menu, or type CTRL-F. But as I say, that's all personal preference.

As for a printed booklet, that is an issue you would have to raise with Steve and Darren.

[MarkusDark]

For the record, I do read documentation before asking questions. And, if I don't, I will usually preface with "I haven't looked this up but can anyone tell me..." mainly because I am at work without a book.

I recently asked a question about why I couldn't load a prefab. I looked into the documentation about how to load one and followed the rules. Nothing appeared. I looked over the prefab section again and didn't note anything mentioning that equipment items would only appear in the Equipment Tab of non-super hero templates (Just found the quick paragraph on page 12 mentioning about the Equipment Tab). Afterall, the "Weapons" prefab loads under the Powers Tab and I figured the same thing would happen for a Champions Universe Equipment prefab.

Not trying to say "I'm right" just letting you know that some of us do look through the rules to find an answer before writing. Just that some times they are not forthcoming or previous examples have shown other actions to be correct.

Also, being such a responsive Customer Service oriented site like this, people find it easier to ask a question than to crack a book and look it up. I can post something here, then surf for a bit and come back and it is answered. So why bother with looking it up when you can get an immediate answer? I see over 50% of the questions that Steve is asked falls under this category as well. It is a price you pay for being such good helping people.

[Vondy]

Originally posted by dsimon
A note here: editing the template is used as an answer for folks that want to change the rules of the system. In my mind, that is a "power user".

The goal of HD was to create a chargen that implemented the rules of the Hero System. That is it's primary purpose in life.

As much as was possible in the time that I had for v1, I included the capability to customize it. Much of this customization (read: changing of the rules) requires template edits.

Is this something that I expect every user of HD to be able to do? Absolutely not. But if you're looking to make a chargen that follows (and enforces) your own special rules, you're going to have to be a bit more than a "layman".

That said, there will be numerous GUI-based rules screens in v2 which will take the place of many of the template edits that are currently necessary. Will editing the template still be necessary for some things? Absolutely. In general, I'm putting all of the "hard coded" rules into rules screens. If you can change something by creating a custom template, then it's not going to be included in the rules screen (at least, not at first). This is an attempt to keep the rules screens from becoming unworkable messes.

I think that in many cases, expectations need to be corrected. HD is a chargen for the Hero System. Nor your own personal modification of the Hero System, but the <i>Hero System</i>. As much as possible, it will allow for customization and house rules....but that is a secondary goal to following the rules as stated in FREd, the supplements, errata and FAQs. v1 hits the primary goal better than any other chargen on the market. v2 will begin to address the secondary goal of customization much more strongly.....

I'm not criticizing your software or your design methodology. My criticism was documentation-centric.

I don't object to someone having to edit a template to implement house rules or make a change (you can't support everything and have a tool that attempts to enforce the core rules), and in that context I think "edit the template" is a fair answer on your part.

I disagree, however, that every power user of Fred, meaning people who want to implement a house rule or an option you don't support, is also a power user in terms of computers, which is why I said I felt the documentation should include instructions for the otherwise computer illiterate on how to do this. That way you can answer "edit the template" without having to worry about whether or not the user is a tech-head or an end-user.

As for me. I'm not using V1. I liked what I saw in terms of functionality, but as a windows user I don't like having to install an additional run time module to operate software and the performance issues were too much. It doesn't help that Sun and MS are whining at eachother over code access, which means there are some unique issues with Java on XP (its not unusual for users to have to manually kill a program that is still running in the background after closing it to get system resources back). I don't have issues with Java, per se, just with Java on Windows.

Since you have been putting so much effort into the performance issue, however, which was my main reason for not using V1 (I'm not a patient man when it comes to computers), I'll be giving V2 a try when it comes out. I do have basic questions about it, however.

1) can I port my metacreator characters over?
2) can I create custom skills (etc) that appear in the skill list?
3) can I save packages or items that I can select from a list instead of rebuilding them or copying them off another character all the time?

I know those aren't particular to this thread, but I'm curious.

[rjcurrie]

D-Man, it might be best to start a separate thread with your questions about version 2. I'd prefer to see this thread stay pretty on-topic because the feedback in it is important to me.

[Simon]

Originally posted by D-Man

1) can I port my metacreator characters over?
2) can I create custom skills (etc) that appear in the skill list?
3) can I save packages or items that I can select from a list instead of rebuilding them or copying them off another character all the time?
1) Doubtful. An export template was made for Hero Creator, but I doubt that it will be updated. Frankly, it's unusual enough for an app like this to have plugins to another (rival) app....

2) Yes.

3) You already can do exactly that with prefabs (v1). v2 will be enhancing the prefab functionality quite a bit to allow even more options and ease-of-edit/creation.

And just a general note on Java: I run WinXP and have had no problems. In general, Sun's JVM for Windows is quite good....I know of very few issues with it. I have not heard of anyone having a problem with HD not shuttind down cleanly for them.

[topcapfan]

I have found the documentation to be extremely useful and very easy to understand.