Plugin Documentation Standards?

[mvlcek]

As mentioned e.g. in http://get-simple.info/forum/post/14630/#p14630, but also critized sometimes by our main testers like Oleg06 and Connie the documentation of plugins is not always the best.

I propose to create some standards for plugin developers (in the wiki) to make it easier for the plugin users.

So far I am using the following sections in my descriptions (on http://mvlcek.bplaced.net):

• general description: what does the plugin do, features
  
• examples (optional): example frontend pages, backend screenshots
  
• installation: how to install, manual steps, for more complex plugins: how to check, if everything works, problem solving, manual workarounds if automatisms don't work
  
• usage: how to use the plugin ("goto plugins/xxx in administration", "enter (% ... %) in page", ...), basic usages first, then advanced usage
  
• API (optional): description of "public" functions that can be called from a template or component, description of parameters, etc.
  
• API for other plugins (optional): e.g. how to use the I18N plugin capabilities in another plugin, how to use a search plugin to search content in non-page files, etc.
  

If the author has no homepage, I think this information should be included in the first post of the support topic (and updated if necessary on new releases). Otherwise the first post of the support task should include:

• short description, maybe link to examples
  
• installation: and problem solving - updated for common problems
  
• usage: main use cases
  
• link to homepage for more information
  

The Extend entry should include a short description and a short installation guide (and links to homepage and support topic in the resp. attributes).

Should there be a plugin-name.txt with descriptions in the plugin zip?

Should there be a description at the beginning of the main plugin file (currently I document the API in my plugins)?

What about a license file in the plugin zips?

What do you think about this?