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?

[polyfragmented]

Otherwise the first post of the support task should include: (...)

The first post should (I am strongly inclined to insert a bold MUST there...) include a link to the most recent version of the plugin in Extend.

It is extremely annoying having to search the support thread for a new version if some time has passed and new posts have been added after an annoucement. New or inexperienced users are likely to consult the forum instead of Extend.

Additionally, new features or squashed bugs could be mentioned. There should be no problem with clutter if only the most recent version is announced in the start post.

[yojoe]

How about addint a html readme (along with installation guide, usage examples etc.) inside plugin archives ?

[mvlcek]

How about addint a html readme (along with installation guide, usage examples etc.) inside plugin archives ?

I'd rather have only a small text file in the plugin (what it does and how to install it), as it's easier to create and easier to read without unpacking the zip.

Thus I'd rather see the most important information in the support topic. There it's easy to update when a new problem/solution is found. As for examples (for frontend functionality), I suppose there is nothing better than to show it on a website.

[Oleg06]

I write a text file all the information to each plugin, collected the crumbs on the forum

Code:

компоненты
<?php get_i18n_component('sidebar');    ?>

для выбора языка

      <div class="language">
<?php
  $fullurl = $_SERVER["REQUEST_URI"];
  if (strpos($fullurl,'setlang=') !== false) $fullurl = substr($fullurl, 0, strpos($fullurl,'setlang=')-1);
  $fullurl .= strpos($fullurl,'?') === false ? '?' : '&amp;';
?>
        <a href="<?php echo $fullurl; ?>setlang=ru">русский</a>
        <a href="<?php echo $fullurl; ?>setlang=en">english</a>
      </div>

Меню

<ul><?php get_i18n_navigation(return_page_slug(),0,0); ?></ul>

для мультиязычных сайтов
<ul><?php get_i18n_navigation(return_page_slug(),0,99, I18N_SHOW_LANGUAGE); ?></ul>

<ul><?php get_i18n_navigation(return_page_slug(),0,99, I18N_SHOW_MENU); ?></ul>
для карты сайта
все страницы
<ul><?php get_i18n_navigation(return_page_slug(),0,99, I18N_SHOW_PAGES); ?></ul>
страницы только из меню
<ul><?php get_i18n_navigation(return_page_slug(),0,99, I18N_SHOW_MENU); ?></ul>
для мультиязычных сайтов
<ul><?php get_i18n_navigation(return_page_slug(),0,99, I18N_SHOW_LANGUAGE); ?></ul>

ДЛЯ ВСТАВКИ СТРАНИЦ В СТРАНИЦЫ
<?php get_i18n_content('news-1'); ?>

<div class="breadcrumbs">
  <a href="<?php echo find_url('index',null); ?>">home</a>
  <?php get_i18n_breadcrumbs(return_page_slug()); ?>
</div>

[Connie]

absolutely necessary:

All files MUST be in UTF-8!
All plugins which show text and produce output MUST support Language files in a standard way (there were discussions on a central plugin-languagefile.folder but I think that would be too much demanded...)

[RobA]

absolutely necessary:

All plugins which show text and produce output MUST support Language files in a standard way (there were discussions on a central plugin-languagefile.folder but I think that would be too much demanded...)

That is a pretty big request! I know my plugins start english language only and I change them over if there is a good reception of the plugin itself (as it is a fair bit of extra works).

Maybe more appropriately is stating IF is supports (or needs to support) i18n using the correct file format, and if so, which languages are available.

On that topic, should a new language be added to the zip in extend, or as a language file (separate download) as I've seen both.

-Rob A>

[Connie]

Rob,

you are absolutely right. I support that.

[ccagle8]

On that topic, should a new language be added to the zip in extend, or as a language file (separate download) as I've seen both

I would prefer it be the the plugin itself, but that's just my preference.

[ccagle8]

mvlcek - can you create a .TXT file template that I can post on Extend that plugin authors can download and edit for their own plugins? I feel this is the best way to push the idea of pluign authors creating a readme.txt file... give them a head start.

I would suggest building it in the "markdown" format so when we decide to display them on the Extend page, they will be HTML formatted. (this is the way WordPress does it when you create a plugin for them)

[mvlcek]

mvlcek - can you create a .TXT file template that I can post on Extend that plugin authors can download and edit for their own plugins? I feel this is the best way to push the idea of pluign authors creating a readme.txt file... give them a head start.

I would suggest building it in the "markdown" format so when we decide to display them on the Extend page, they will be HTML formatted. (this is the way WordPress does it when you create a plugin for them)

OK, I'll do it. May take a few days, though.

[ccagle8]

Thanks! When youre done, post it here so we can all comment on it and make sure it's complete, yet not too complicated that no one will do it.