Universal Format for Mod Instructions

Kingphish posted 4th of April 2011 in Community Voice. 5 comments.

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.

 
Comments
·Oldest
·Top
Please login to post a comment.
AlexT
Actually there is already defined format for readme file for every Dolphin mod:

http://www.boonex.com/trac/dolphin/wiki/DolphinExtensionReq#ReadmeFiles

It splits into 4 main sections:
- Product owner info
- Product info
- Installation manual
- User manual

This is wiki page, so everyone can edit it. It is very short now, I see that you have some good examples to add, so feel free to edit it. Please leave the above 4 sections (just edit it, by adding examples, description, etc), add more see more optional sections, like notes, troubleshooting - it will encourage developers to add it to the every mod, so it will be less frustration from customers.

We are trying to force all developers to follow the standard, but we don't check every mod - so we have to rely on developers that they will follow it.
From out side - during mod certification process we check the mod for the standards and all certified mods are comply with these rules.
Kingphish
Thanks AlexT. Yeah, I see now that folks on here don't like rules (even the small ones), but non-burdensome rules make things easier for everyone, and a format for installation instructions is not burdensome. BURDENSOME is having to go back to a developer-seller multiple times for clarification on their instructions.

I suggest all buyers demand a copy of the instructions PRIOR to purchasing any product. There is definitely a TRUST issue with developers on here and their reluctance to do the minimal see more things that are asked of them. I've purchased $200 of mods in the market since January (2011) reluctantly, and intend to spend more, but I can't trust that I'll get what I need from the market, so I'm developing my own listing of trusted developers. I WOULD RECOMMEND ALL BUYERS (especially the news one) to do the same. If a developer-seller is unwilling to meet minimum requirements, they are not deserving of business.

"Damn it Superman, Bizarro strikes again."

As to what can be done -- enforce the rules; they are not burdensome. Don't allow them to sell in the Market if they don't conform. Also, give them at least ONE EXAMPLE of what is expected with regards to the Installation Instructions so they can have a sense of what they are doing right or wrong. There is no physical reference point, so they'll do things different, which is the reason why there is so much variance. And, it would be helpful to say more (rather than less) under each of the bullet points to explain what is needed.
Kingphish
Also, I'd like to see Boonex link content to other blogs and forums on the subject, so while someone is reading the Wiki they are able to pull up via popup window real life examples. For example, if I am reading the above Wiki, I would be click on the wordlink (via popup) to see a member-produced forum that's related to the word (e.g., user manual).
houstonlively
I haven't had any too many complaints about installation procedures provided with extensions that I've purchased. One of my biggest gripes would be upgrading from one version to the next. Very few developers keep a detailed change log. Some of them may think they do, but an ongoing list of what features are added, or what bugs were fixed, is practically useless. Change logs should detail which files were changed, any new files, removed files, database changes..if any, and detailed upgrade procedures. see more It makes no sense to upload all files and uninstall/reinstall, if all that has changed are few files.
tomakali
Id like to have an appstore for my Dolphin site...
it would be so much easier to install, upgrade
atleast something like https://addons.mozilla.org/en-US/firefox/extensions/?sort=created
Classified by Versions, Experimental etc
 
 
Below is the legacy version of the Boonex site, maintained for Dolphin.Pro 7.x support.
The new Dolphin solution is powered by UNA Community Management System.
PET:0.14293503761292