Questions You Should Answer When You Document KDE

Listed below, is a list of questions. When you think you have finished your documentation, you should review this list of questions and make sure that you have answered all of them (or that that particular quesiton does not apply in this application).

You may need to ask the application developers some of these questions, but please try to answer as many as you can before you contact the author. If you contact the developer with a small set of specific questions, you will probably get a more helpful response, then if you simply send this questionaire to the developer.

Some of the questions are marked (Developer), which simply means the question is written specifically to be answered by the developer. This does not mean you have to ask the developer, but these questions will often require input from the developers.

I have also marked some questions with a section name (Example: [Introduction]). This identifies where in your documentation this information should be used.

Remember!!!

This is only a guide to help you write more effective and complete documentation. Please do not think this is the only information you need to include to create useful documentation. This is an aid for you, not a crutch.

Identification

• What's the purpose of your application ? [Introduction]
• Can you briefly describe your application? [Introduction]
• What are your application's key features? [Introduction]
• What are you particularly proud of in your application? (Developer) [ Introduction]
• What are the differences between your application and other applications of the same type? [Introduction]
• What type of user is your application intended for? [Introduction]
• Who wrote it ? (Names and URLs please) [Credits]
• Is the current author/maintainer different from the original author/maintainers [Credits]?
• What is the licence under which your application is released? [Credits]
• Does your application have a home page? (URL please) [Introduction and Installation]
• Is there a mailing list for this application? If so, what material is suitable for this mailing list? [Introduction]

Installation (obviously all these questions should be answered in the [Installation] section)

• What are the downloading instructions? (FTP site, in KDE's CVS or not and where in this CVS, mirrors,...)
• Is there a stable and a developmental release?
• What is it built upon that should be previously installed?
• Are there special compilation or instalation instructions beside ./configure, make, make install?
• Does installing the libraries for this application risk breaking other applications (Are they using bleeding edge libraries that may not work correctly)?
• Is this application part of any of the KDE packages (kdenetwork, kdebase, etc)?
• Does it require some configuration before being able to run?
  If yes, can you give some instructions?

Functioning

• Is this application themeable/use skins/etc?
• Does this application interoperate well with another seperate application? If so, how?
• What system settings does this program rely on (Address books, etc)?
• Does it give access to an existing system functionality, like PPP?
  If yes, can you say a couple of words about it, or give a pointer?
• Are there some special concepts or terms implied by your application?
  If yes, can you explain them in simple terms?
• Are their some pecular hints and tricks you could give to users about your application's usage?
• Which dialogs or menus are hidden that we, authors, may miss when trying to run your application? (Developer)
• Have you made a test suite or sample files we could use to run your application? If yes, can you please send them? (Developer)
• Are there some features that need special rights or previous steps?
• Are there some command line options, and if yes, can you explain them shortly?
• What is the configuration file format/syntax? [Advanced Features or Appendix]
• Is your application scriptable?
• Is your application dockable?
• What's your application's behaviour with respect to components? (Developer)
• Is there an API associated with your application, and if yes, can you describe it? (Developer)
• Where is this application installed on your system (directory and menu locations)?
• Are there Howtos (PPP HOWTO, etc) or other documents that may be useful for setting up this application? If so, where can they be found?
• Does this application support plug-ins, extensions or any other additional items (template files, dictionaries,etc)? If so, where can users get newer/additional copies?

Quality

• What are the most common problems, and their solutions, or the known bugs? (Developer)
• Are there some usual questions that users ask, and what are their answers? (Developer)
• What may be the missing features? (Developer)
• What are the enhancements since last revisions? (Developer) [Revision History]
• What future developments do you plan or could be done? (Developer) [Introduction]

Return To The Home Page