Hi,
I have had a dialog with Michal Čihař regarding work on a new documentation for the phpMyAdmin project. The reason I am sending out this mail on this mailing list is to ask for input on the format of the documentation.
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.
Best regards, Cato Auestad
Hi
Dne Mon, 5 Apr 2010 17:54:25 +0200 Cato Auestad bleakgadfly@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.
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.
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-Forma... [2]:http://www.docbook.org/ [3]:http://sphinx.pocoo.org/
Michal Čihař a écrit :
Hi
Dne Mon, 5 Apr 2010 17:54:25 +0200 Cato Auestad bleakgadfly@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
Hi
Dne Tue, 06 Apr 2010 07:36:00 -0400 Marc Delisle marc@infomarc.info napsal(a):
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.
Well but each phpMyAdmin package contains documentation matching the environment. We currently have requirements for PHP 5.2 and MySQL 5, what is not something you could call historical.
Also, changing the contents is one thing; changing the format is another.
It definitely is, on the other side when there will be bigger changes in documentation, it's better to choose more flexible format, which will allow us for example to provide manual in PDF format.
I have no experience with Texinfo. Would it adapt easily to our Pootle translation server?
Yes, it should work with Po4a as well as our existing HTML documentation (but I have not tested it so far).
Michal Čihař a écrit :
Hi
Dne Tue, 06 Apr 2010 07:36:00 -0400 Marc Delisle marc@infomarc.info napsal(a):
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.
Well but each phpMyAdmin package contains documentation matching the environment. We currently have requirements for PHP 5.2 and MySQL 5, what is not something you could call historical.
I see your point. Looking for example at some FAQ entries
1.1 (PHP 4): delete (but do not reuse the number 1.1?)
1.2 keep
1.3 (PHP 4): delete
1.4 (IIS crash) I don't know but the PHP bug report is old and was marked "bogus"
1.5 (ISAPI not stable) I don't know, is ISAPI better now?
1.6 (Personal Web Server): this relates to Windows NT 4, delete
1.15 Maybe still relevant for a user who has upgraded MySQL without running the update program.
etc ...
So some entries would be easy to replace with something like
1.1 (deprecated)
but some need research.
On Tue, Apr 6, 2010 at 1:46 PM, Michal Čihař michal@cihar.com wrote:
Hi
Dne Tue, 06 Apr 2010 07:36:00 -0400 Marc Delisle marc@infomarc.info napsal(a):
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.
Well but each phpMyAdmin package contains documentation matching the environment. We currently have requirements for PHP 5.2 and MySQL 5, what is not something you could call historical.
Also, changing the contents is one thing; changing the format is another.
It definitely is, on the other side when there will be bigger changes in documentation, it's better to choose more flexible format, which will allow us for example to provide manual in PDF format.
I have no experience with Texinfo. Would it adapt easily to our Pootle translation server?
Yes, it should work with Po4a as well as our existing HTML documentation (but I have not tested it so far).
I have never tested Po4a and the only dealings I have had with Pootle is on the Tor Project translation website. I can try it out and see how it works with Texinfo, but I am not sure how you guys want to try and migrate your current documentation/FAQ. I had in mind making a more comprehensive documentation, more or less from scratch.
I am also not sure how your current translations interact with your current documentation/FAQ.
Cato.
-- Michal Čihař | http://cihar.com | http://blog.cihar.com
Download Intel® Parallel Studio Eval Try the new software tools for yourself. Speed compiling, find bugs proactively, and fine-tune applications for parallel performance. See why Intel Parallel Studio got high marks during beta. http://p.sf.net/sfu/intel-sw-dev _______________________________________________ Phpmyadmin-devel mailing list Phpmyadmin-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/phpmyadmin-devel
Hi
Dne Tue, 6 Apr 2010 14:21:25 +0200 Cato Auestad bleakgadfly@fsfe.org napsal(a):
I have never tested Po4a and the only dealings I have had with Pootle is on the Tor Project translation website. I can try it out and see how it works with Texinfo, but I am not sure how you guys want to try and migrate your current documentation/FAQ. I had in mind making a more comprehensive documentation, more or less from scratch.
I am also not sure how your current translations interact with your current documentation/FAQ.
Po4a basically extracts text from the document and feeds it into po file, which can be later translated by standard tools. Pootle is just web interface for translating po files.
In infinite wisdom Marc Delisle marc@infomarc.info wrote:
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.
One way to maintain the old urls would be start versioning the new documentation. Thus, the 3.x release of phpmyadmin would have its documentation living at http://www.phpmyadmin.net/documentation/3/ or http://www.phpmyadmin.net/faq/3/en/ or http://www.phpmyadmin.net/changelog/3/en/. The mysql documentation has been written this way - http://dev.mysql.com/doc/refman/5.0/en/index.html. Apache documentation uses similar url schema - http://httpd.apache.org/docs/2.2/ or http://httpd.apache.org/docs/1.3/
A good reference on (somewhat) related topic is w3.orgs "Cool URIs don't change" http://www.w3.org/Provider/Style/URI.
On 04/06/2010 09:01 PM, Raj Shekhar wrote:
In infinite wisdom Marc Delisle marc@infomarc.info wrote:
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.
One way to maintain the old urls would be start versioning the new documentation. Thus, the 3.x release of phpmyadmin would have its documentation living at http://www.phpmyadmin.net/documentation/3/ or ...
Using html format works for me, but I agree that it could use some attention.
For the docs on the website that might be a nice idea. A rewrite rule could map documentation/latest to the current version number, which could be used to reference it from a version independent perspective.
In infinite wisdom Cato Auestad bleakgadfly@fsfe.org wrote:
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.
To paraphrase a famous quote [1],
"Documentation is like sex: any form of it is better than nothing."
[1] "Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing." — Dick Brandon.
-
Cato Auestad -
Herman van Rink -
Marc Delisle -
Michal Čihař -
Raj Shekhar