[Phpmyadmin-devel] The format of the new documentation.

[Marc Delisle]

Michal Čihař a écrit :
> Hi
> 
> Dne Mon, 5 Apr 2010 17:54:25 +0200
> Cato Auestad <bleakgadfly at fsfe.org> napsal(a):
> 
>> I have had a dialog with Michal Čihař regarding work on a new documentation
>> for the phpMyAdmin project.
> 
> Just to describe a background here a little bit: I originally wanted
> this to be a GSoC task, but after Marc pointed out that documentation
> work is not allowed there, I opened a position with similar description
> at sf.net website. That's how Cato has contacted me.
> 
> The reason for this is that I feel that current documentation in form
> of FAQ is not really easy to read and contains many historical things
> which basically have no relevance today.

Yes, but this will be difficult to determine. Lots of users are running 
"historical" servers. We can probably remove some entries but remember 
that in old forum posts we referred to FAQ # and people are still 
finding those posts.

Also, changing the contents is one thing; changing the format is another.
> 
>> Texinfo is my preferred way of writing documentation, and at the moment the
>> only format I am used to write in.
>> I would like to create a discussion around what format in which the
>> documentation should be written in.
> 
> Texinfo[0] is the official documentation format of the GNU project and
> it has wide range of output formats [1]. On the other side it is still
> TeX with all pros and cons you get with it.

I have no experience with Texinfo. Would it adapt easily to our Pootle 
translation server?

> 
> There are lot of other alternatives we could use, just to mention some:
> 
> - Docbook (XML markup, widely used format) [2]
> - Sphinx (text markup, generates nice html docs with search) [3]
> - stay with HTML as we use it right now
> 
> [0]:http://www.gnu.org/software/texinfo/
> [1]:http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Output-Formats
> [2]:http://www.docbook.org/
> [3]:http://sphinx.pocoo.org/


-- 
Marc Delisle
http://infomarc.info