Creating User Documentation

Manuals, Guides and Comments on Code


star




Creating User Guides



This was an interesting excursus from our usual web design curriculum: we were to design user documentation for the Windows Snipping Tool, which of course is invaluable for taking screen "snips" quickly and efficiently without having to use the "Prnt Scrn" button and then paste the clipboard contents into an image editing program for further cropping/resizing etc. (Click the image to view the PDF)


Windows Snipping Tool User Guide

Figure 10: The Windows Snipping Tool User Manual



Principles of Creating User Documentation



  1. User documentation must be concise.
  2. It must be designed for the user's experience level (in this case, for the beginner to MS Windows).
  3. It must contain a cover page and a table of contents.
  4. It should serve to enlighten rather than confuse the user. For example, it is no use writing a 100-page manual on a program like the snipping tool that explores vastly irrelevant or tangential topics.
  5. It should contain an appropriate amount of images (screenshots, stock photography, etc.) to make it refreshing reading and give the reader something to examine while absorbing the text.
  6. User documentation should be written in an orderly fashion and not jump from one topic to the next. Each chapter should build upon the knowledge the reader has gained while reading preceding chapters, while bearing in mind that he or she may not remember everything and revisiting certain important topics as necessary.

We have already seen examples of documentation in our resources section on C# programming. These are good, albeit lengthy examples. There's a saying that goes,

Take what you need and leave the rest.

Nothing could be said more aptly about user manuals, documentation and guides, etc. You will need to find suitable material for you to read and then take what is necessary to enhance your own knowledge.



Commenting Code



As we have seen, the importance of commenting code cannot be understated. It provides a reference for the programmer to remind himself or herself what he or she was doing at that particular time. It allows others who are working with the same source to understand this and even communicate with one another. In short, commenting code is a way of adding information that is totally user readable to code that is occasionally complicated or obscure. Comments can even help make complicated code easier by reminding the programmer of shortcuts and more efficient methodologies of programming.

Usually "documentation" is thought of as being user guides, manuals, introductions and tutorials, but this is in fact external documentation whereas comments to code, be it HTML, CSS, JavaScript, PHP, C#, or any other language, is considered internal documentation, and documentation it is indeed; and the better it is written, the more prudent and precise is the commenter. It is a very good idea to add comments to code whenever they seem helpful or necessary.




© 2016-2020 Leo Coroneos
Certificate IV in Information Technology
South Regional TAFE, Albany WA Australia