Components of online help and printed user guides for software applications
Discussion started by Gina Goodson Wadley , on 28 July 02:12 PM

Does anyone have any articles or books to suggest about components of online help and printed user guides for software applications?  We all seem to have different points of view of what should be included, and I know it depends upon the type of information, delivery, and audience, as well as other factors. 

I have a subscription to and skimmed through these:  

·         Read Me First! A Style Guide for the Computer Industry, Third Edition  

·         Microsoft Manual of Style for Technical Publications, Third Edition  

·         Letting Go of the Words: Writing Web Content that Works  

·         Other books referenced on the Technical Editing SIG  

I'd like to see something like this with the various possible components of the documentation for a user guide for software applications (not necessarily in this order):

·         Copyright info  

·         Table of Contents  

·         Introduction  

·         Overview  

·         Concepts  

·         Examples  

·         Tutorials (multimedia)  

·         Tasks (separated by basic and advanced)  

·         Reference  

·         Troubleshooting  

·         FAQs  

·         Index  

·         Glossary  

I'd also like to see the components of a quick start or getting started guide.   Essentially I want to make sure that the users get a good overview of concepts and examples up front, tasks in the middle, and references at the end.  I tend to write to teach, being a former educator and instructional designer.  But I'm not trying to write a training guide.  I hope someone out there has some suggestions.   Thanks!



You will need to be a member of this group first before you can post a reply.
Gina Goodson Wadley
Sending you a message on the way, I can't find the link to your thesis on lulu.
Monday, 17 October 2011 15:28
Dr. Gloria A. Reece

I have placed a link to my M.S. Thesis at my author spotlight. Please let me know if you'd like to collaborate on an eBook. The taxonomy that you are searching for is given on page 30 of the thesis. Here is the link to the spotlight:

--Gloria Reece

Saturday, 15 October 2011 05:20
Gina Goodson Wadley

I really appreciate all of this information. I just sent you a message with my contact info. I definitely think a book would be a good idea, since there seems to be missing current resources on the Web on the subject.

Wednesday, 03 August 2011 16:52
Dr. Gloria A. Reece
Hi Gina,

Yes, there is an error in the compiled PDF file. I am in the process of creating a better PDF document. There is a taxonomy in the thesis that might be very helpful to you.

And, yes, you are correct, Bloom's Taxonomy may not be highly helpful to you for this task. If you need more information on Bloom's Taxonomy, please let me know. Currently, there are some changes being made to it. Bloom's Taxonomy is useful for framing objectives and outcome statements for teaching and learning tasks.

As for the taxonomy in the thesis, I can send you a print copy of the original that is a bound archival copy--the same product that you'll find in a library's special collections. If you would like for me to send this material to you, please let me know. I will also check my original files and add this missing material to the PDF file. It is a pretty good taxonomy that took a good bit of time to research, design, and write.

If you would like to team with me to write a new book from this material, I'd be happy to discuss the project with you. It seems like there's a really good match with our backgrounds and experiences. So, let me know your thoughts on this possibility, too.

You might also check some material on object-oriented programming. I like to read material by Grady Booch. Books on UML are also helpful. Sometimes you can derive taxonomies from these types of explorations. There are also some good products for object oriented programming. Checks of evaluation copies for these products might also be helpful.

When I delve into these areas, I generally like to have a specific problem that I want to solve in mind. For example, in your case, it would not be to define a taxonomy per se. Rather, it might be to complete a familiar transaction and then see what results from that task with regard to a taxonomy. So, I guess what I'm saying is that I do lots of mental elaboration (uses Bloom's Taxonomy at a higher level) and then take copious notes. Then, I do lots of creative blockbusting as i discuss in the M.S. thesis. (There's a chapter on Creativity in the book, too.)

So, just let me know if I can send you any additional materials. I do have a web version of the HCI bibliography. And, it has previously been housed by ACM.--Gloria Reece
Wednesday, 03 August 2011 16:45
Technical Publications
Hi Gina,
I read "Writing Software Documentation: A Task-Oriented Approach" by Thomas Barker in college (I was lucky enough to be taught by him as well), and I still use it as a reference today. Here's the link to the book's Web site:
It does cover some basic items, but there are a few chapters, like chapter 10 - Designing for Task Orientation, that might cover some of what you're looking for.

Tuesday, 02 August 2011 13:01
Gina Goodson Wadley
Hi Gloria,

Thanks very much for the information. I was actually searching for ways to organize the components of online help and user guides such as concepts and FAQs. It's not the content that I'm lacking. It's just the best way to organize it. (I apologize for not being more specific.) I was also limiting my search to post 2005 (or so) to make sure Web 2.0 and social media were included.

Maybe a better term of what I'm looking for is "taxonomy", which I just realized by looking over your thesis. There's a reference to Figure 5. An Expected Taxonomy of a Content–based Information Structure in a Dual–delivery Project (page 87) in the Figures list, but I can't find the figure in the PDF. I just found a blog post entitled Bloom’s Taxonomy in Technical Writing by Sujoy Dutta which is close to, but not precisely what I'm trying to find ( I'm trying to make the case of structuring online help and user guides to cover these components (e.g., explaining the concept in a user-centric way -- not software-centric where the writer describes "what this button does", but what problem the software can solve for the user).

It would be great to see your thesis evolve into a book!

Monday, 01 August 2011 13:40
Dr. Gloria A. Reece
Hi Gina--

I'll respond based upon my experience with single-sourcing for multimodal delivery for a large-scale product development engineering organization.

One of the best ways to approach the development of this sort of content is to involve the developers and stakeholders in some way. One way is to place your ideas for content on sticky notes in an accessible location and allow others to give you feedback. Once you give folks a manipulative (the sticky notes), then, it gives them something to move around and think about--mental elaboration. Once they can see the structure visually, then, they get new ideas and start annotating the chart. It's really amazing to watch this process occur!

Once things get stabilized, I'd recommend moving to an electronic method for providing the results. Then, that can be edited very easily.

Another way to get content is to use the strategies of a journalist and search through the comments in computer code or design documentation. Sometimes comments in computer code can be descriptive enough that you can extract some content for these areas from that material. Of course, this sort of technique requires access to the code.

Content guidelines for the product may also have most of the material that you need. When I managed a documentation department one of the first things that I did was to write four documents: Formatting Guidelines, Content Guidelines (included legal approvals), Production Guidelines, and Directory Structure (configuration management) Guidelines. The content guidelines provided the information that you are seeking here.

Anyway, I'm hopeful that this information is helpful to you. My M.S. thesis was on a single-sourcing topic. It's a free download here: It also has an extensive bibliography that covers several disciplines. You may find something there that is helpful.

Saturday, 30 July 2011 01:54