Universal Format for Mod Instructions

You know, I've bought quite a few products in a very short period of time, and the one thing that bothers me from one product to another is "INSTRUCTIONS!" Trying to read some of the instructions is like I've been shocked by a taser (Don't tase me bro!), which I believe defies the reason for having instructions. That is, instructions are suppose to (at least) minimize questions rather than provoke additional questions or in my case, provoke confusion.

Now, people should not have to be "Sensei" type developers to use the Dolphin product or install Dolphin mods. One of the main purposes of Dolphin (in my opinion) is to make web development easier for people (regardless of experience levels), and by easier I mean that with instructions and few questions, people should be able install mods, use and further develop Dolphin, otherwise, why bother doing any of this? If one of the tenets of the Dolphin platform is NOT to make the software easier to use for various experience levels, why not then just start from scratch? I tell you, it would kill the frustration level.

Most of you might be against this idea, but I think as a community, we should create "standard work" around what goes into the instructions of products created in the Market. Standard work is a Lean Manufacturing term which is basically the most efficient and product way of producing something, and in this case, "Mod Instructions".

My thoughts about the sections:

• Use of the term "Installation" instead of "Directions".  I have downloaded a number of instructions that have installation as a heading, but what I think they mean is Direction not "Installation". Installation is a word that I don't believe best captures the act and it can be kind of confusing. I understand that Unity is a diverse community with people from all over the world that is why it is important to come to some kind of consensus to make dealings in the market easier for everyone regardless of experience level. Directions are commands and Installation isn't.
  
  
• Use of the "Instruction". Using instructions as the title of the document is fine, but the actual step by step are generally instructions, however, each step is a direction. Also, each step MUST be clearly defined in the directions. What I found is that there is A LOT of inference that goes on in the directions; that is, the developer-seller leaves it up to developer-buyer to guess a step(s) rather than simply telling the developer-buyer exact what to do.
  
  Here is an example:
  
  "Upload the folders and files in the folder."
  
  What it should have said:
  
  "Upload the Main Folder (including files) from the unzip file into your website's root (main) directory."
  
  This level of detail reduces the need for and dependency on the developer-seller to address issues of minor concern.

I'd like to propose a format for installation instructions to be used for all mods. The recommended installation instruction format will only include the following the sections:

1. Introduction. Here you can say whatever you want. I noticed that developer-sellers like to include marketing-type information, so here is a good place to describe the product and what it will do, as well as other information.
   
   
2. Developer-Seller information. Provide contact information. Website. Demo URL (if any). Email address. Also, I would pu the legal information (trademark, copyright, etc.) and terms of use (e.g., "changing this mod for commercial use is prohibited unless prior expressed (written) permission is obtained ... for expressed permission, please contact ...").
3. Version information. Include the date of first release of the particular version. I would also suggest listing for the buyer the version compatibility with various versions of Dolphin products. That is, the developer-seller should answer: What Dolphin platform(s) is compatible with the particular mod for sale? List them all if it's true; at least, list all that apply. Some people don't upgrade to the current version of Dolphin, so it would nice to know, what's compatible.
   
   
4. Directions. How-to words and sentences go here and they should be step-by-step (COMMANDS) described fully/adequately.
   
   For example (commands): 1) Put your left hand on top of your head. 2) Next, stick the forefinger of your right hand in the right nostril of your nose and leave it there. 3) Now, try to whistle your favorite song. Use simple sentences. If you have to add an "AND" then break the sentence up into two or more sentences.
   
   
5. Troubleshooting. I like this -- great idea. I only think I've seen this once, but it's a common sense approach to helping the buyer figure out what they did wrong, and it shows that the developer-seller is thoughtful and professional. Further, it helps the buyer work through almost every conceivable issue before they contact the developer-seller for help. Without it, contacting the developer-seller is the first thing most buyers do, which can be a waste of time for the developer-seller, especially if the concern is one that can be resolved without the help of the developer-seller.
   
   
6. Notes. This section is dedicated for other information. Anything else that the developer-seller thinks the buyer should know. For example, I understand the custom template may have an adverse impact on some of the mods; that is good information to know BEFORE most people buy mods and/or custom templates.
7. Change Log (as per HoustonLively). Trying to read and understand the directions from some of these mods is becoming a fulltime job detail which files were changed, any new files, removed files, database changes ... if any, and detailed upgrade procedures.
8. Modification Instructions & Code (if possible). If certain modes are impacted by custom templates, it may make sense to include the code OR provide some additional information regarding the particular files that need to be modified to accommodate the new mod.

It would be nice to have some uniformity. I'd appreciate any and all comments (as long as they are not belligerent). Adding to the list isn't a bad thing as long as they make the instructions more effective.