better plugin documentation
Peter Krautzberger
I would like to send out a plea for improved plugin documentation on
the plugin pages on wordpress.org. I know, we're all busy and not
having published plugins myself I'm not one to talk. But before you
flame me hear me out.
For example, what Martin Fenner's bibtex importer plugin actually was
a bit difficult to grasp for me without actually installing it. To
exaggerate: which bibtex user thinks of reducing a bibtex entry to its
url part when the plugin is called "importer"?
A simple description on the plugin page could help:
"Rudimentary bibtex import by reducing bibtex entries to their url
(ignoring entries without url) and adding them to the wordpress link
list. That way, links to papers can be added to any wordpress content
without manual conversion from bibtex (works especially well with the
link-to-link plugin for easier access to those links)"
Similarly, the kcite plugin could benefit from some screenshots to
show both setup and actual results.
The background: Recently we started a small project at http://boolesrings.org
. The idea behind it is a bit different from the other projects
represented on this mailing list. The goal is to make a case for
wordpress as a modern homepage solution for scientists. It's
surprisingly tough to find and test suitable plugins -- and to get an
idea of what the plugin actually does without installing it (but
that's going to be another post).
Phillip Lord
This is not a terribly flametastic group, so I wouldn't worry about that
to be honest.
Your plea for better documentation is entirely reasonable. Kcite, for
example, does have documentation, but it is not the best documentation
in the world. This is made worse by the reality that there are several
places that we *could* document kcite -- if we put lots of stuff up on
Wordpress.org, I get asked for documentation of knowledgeblog.org.
I will try and update the documentation, but it is worth saying that
contributions are always welcome; this can include documentation as well
as code!
Phil
--
Phillip Lord, Phone: +44 (0) 191 222 7827
Lecturer in Bioinformatics, Email: philli...@newcastle.ac.uk
School of Computing Science, http://homepages.cs.ncl.ac.uk/phillip.lord
Room 914 Claremont Tower, skype: russet_apples
Newcastle University, msn: m...@russet.org.uk
NE1 7RU twitter: phillord
Fenner...@mh-hannover.de
You are of course right about the need for better documentation. To make it easier to add documentation to my "BibTex Importer" plugin, I will start hosting it on github - my "ePub Export" plugin is already there: https://github.com/mfenner/ePub-Export. As Phil said, contributions are always welcome.
I would think that the best place for documentation is in the plugin (e.g. readme.txt).
Best,
Martin
-----Ursprüngliche Nachricht-----
Von: wordpress-fo...@googlegroups.com [mailto:wordpress-fo...@googlegroups.com] Im Auftrag von Phillip Lord
Gesendet: Dienstag, 16. August 2011 10:43
An: wordpress-fo...@googlegroups.com
Betreff: Re: better plugin documentation
Jodi Schneider
Peter,
You are of course right about the need for better documentation. To make it easier to add documentation to my "BibTex Importer" plugin, I will start hosting it on github - my "ePub Export" plugin is already there: https://github.com/mfenner/ePub-Export. As Phil said, contributions are always welcome.
I would think that the best place for documentation is in the plugin (e.g. readme.txt).
Peter Krautzberger
@Philip I think wordpress is the crucial place because it will reach
the average wordpress user. But I think this does not necessary mean
the documentation has to be there, it can be a simple link elsewhere.
@Martin github is a great idea but I agree with @Jodi that the readme
is important; again, links are great.
I promise to eat my own dogfood with our first little redundant
plugin.
Peter.
On Aug 16, 9:20 am, Jodi Schneider <jschnei...@pobox.com> wrote:
> > Peter,
>
> > You are of course right about the need for better documentation. To make it
> > easier to add documentation to my "BibTex Importer" plugin, I will start
> > hosting it on github - my "ePub Export" plugin is already there:
> >https://github.com/mfenner/ePub-Export. As Phil said, contributions are
> > always welcome.
>
> Many thanks! I'll happily follow this and any other documentation efforts
> that are on github. :)
>
>
>
> > I would think that the best place for documentation is in the plugin (e.g.
> > readme.txt).
>
> It's best to have easy access to the documentation before it's installed. So
> while readme.txt is a great place, do ensure that it's obvious (i.e. in
> descriptions about the plugin) that this can be seen without downloading,
> -Jodi
>
>
>
>
>
>
>
> > Best,
>
> > Martin
>
> > -----Ursprüngliche Nachricht-----
> > Von: wordpress-fo...@googlegroups.com [mailto:
> > wordpress-fo...@googlegroups.com] Im Auftrag von Phillip Lord
> > Gesendet: Dienstag, 16. August 2011 10:43
> > An: wordpress-fo...@googlegroups.com
> > Betreff: Re: better plugin documentation
>
> > This is not a terribly flametastic group, so I wouldn't worry about that to
> > be honest.
>
> > Your plea for better documentation is entirely reasonable. Kcite, for
> > example, does have documentation, but it is not the best documentation in
> > the world. This is made worse by the reality that there are several places
> > that we *could* document kcite -- if we put lots of stuff up on
> > Wordpress.org, I get asked for documentation of knowledgeblog.org.
>
> > I will try and update the documentation, but it is worth saying that
> > contributions are always welcome; this can include documentation as well as
> > code!
>
> > Phil
>
> > > I would like to send out a plea for improved plugin documentation on
> > > the plugin pages on wordpress.org. I know, we're all busy and not
> > > having published plugins myself I'm not one to talk. But before you
> > > flame me hear me out.
>
> > > For example, what Martin Fenner's bibtex importer plugin actually was
> > > a bit difficult to grasp for me without actually installing it. To
> > > exaggerate: which bibtex user thinks of reducing a bibtex entry to its
> > > url part when the plugin is called "importer"?
>
> > > A simple description on the plugin page could help:
>
> > > "Rudimentary bibtex import by reducing bibtex entries to their url
> > > (ignoring entries without url) and adding them to the wordpress link
> > > list. That way, links to papers can be added to any wordpress content
> > > without manual conversion from bibtex (works especially well with the
> > > link-to-link plugin for easier access to those links)"
>
> > > Similarly, the kcite plugin could benefit from some screenshots to
> > > show both setup and actual results.
>
> > > The background: Recently we started a small project at
> > > make a case for wordpress as a modern homepage solution for
> > > scientists. It's surprisingly tough to find and test suitable plugins
> > > -- and to get an idea of what the plugin actually does without
> > > installing it (but that's going to be another post).
>
> > --
> > Phillip Lord, Phone: +44 (0) 191 222 7827
> > Lecturer in Bioinformatics, Email:
Phillip Lord
>>
>> I would think that the best place for documentation is in the plugin (e.g.
>> readme.txt).
>>
>
> It's best to have easy access to the documentation before it's installed. So
> while readme.txt is a great place, do ensure that it's obvious (i.e. in
> descriptions about the plugin) that this can be seen without downloading,
> e.g. at
> https://github.com/mfenner/ePub-Export/blob/master/readme.txt
The plugin page on wordpress is actually generated from the readme.txt,
so you can always see it there. I wouldn't necessarily expect it to be
in the versioning system as it might be generated itself.
Phil
Phillip Lord
> @Philip I think wordpress is the crucial place because it will reach
> the average wordpress user. But I think this does not necessary mean
> the documentation has to be there, it can be a simple link elsewhere.
"Phillip" -- Phil is easier:-)
The thing is that you are assuming that interested parties are Wordpress
users looking for plugins. On the other hand, they might be scientists
who see the content on knowledgeblog and think, well, how do I do that.
For them, Wordpress is an afterthought, and they will look on
knowledgeblog.
Most of the comments I have got have been "I looked for installation
instructions on your site and couldn't find them". The answer "they are
on wordpress.org" doesn't really help.
The solution, is to generate the documentation from a single source.
It's where will go eventually, but all takes time.
Phil
Peter Krautzberger
side that wants to achieve more. I absolutely agree to single source,
multiple display.
And yes to your feature request: @universe, please, more hours to the
day...
Peter.
On Aug 17, 5:52 am, phillip.l...@newcastle.ac.uk (Phillip Lord) wrote: