Hi,
[Note: intentionally crossposted to a lot of addresses.]
It is a long time TODO item on the phpdoc TODO list, that we should set up a website specifically for the documentation team. Now as we are preparing for an initial version of the site, and livedocs is in the works, a need for a joint documentation website came up, which would include information and tools for people working on the php-doc, pear-doc, pecl-doc, php-gtk-doc, smarty-doc and livedocs stuff. Since livedocs will hopefully help us unify our systems, and share our experience and detached development more easily, it would be desirable to set up a joint website. It would also help translators to move around the projects, and contributors to help out in more than one project.
The address of this site will be something like doc.php.net or docs.php.net. The hardware is going to be provided to us via Mehdi (under preparation). This site should host a lot of stuff related to the phpdoc tools:
- documentation howto (moved here from php.net, updated/extended for the different projects)
- revcheck output (translation uptodate checks)
- locally hosted build logs (or make test outputs, or just links to remote build logs, so translators will easily find out what is wrong, if files of a language does not seem to update)
- functable output (undocumented functions, etc)
- a public livedocs interface to the manuals
- more: link and ID consistency checks, etc.
These are the ideas we have on what to include on the website about the PHP manual. This site would ideally include a lot more information about the different documentation teams: TODO items; help for newcomers to join the teams (build systems, organization, etc); a list of all mailing lists related to the documentation teams (even not listed on php.net).
Since I am admittedly not working in any of the documentation projects apart from phpdoc, I only have remote ideas on what can we put up on this new site helping those working in the other teams. I have put together a simple homepage plan for this site to start discussion (attached). All of the links are supposed to be local: the links representing the different subprojects will lead to local pages presenting more information about those doc subprojects. The different documentation helping tools are supposed to be accessible on this machine. Mehdi is also preparing a version which includes working revcheck outputs and other stuff, but that is not yet ready for public review (at least this is my understanding).
Now I would like to ask you to just think about this a bit, and if you are interested in the development, please provide your opinion on how would it be best to discuss the further directions (crosspost replies, a designated mailing list, personal emails, IRC, or something else?)
Have a nice day, GobaTitle: PHP Documentation Teams
What is this site?
There are different documentation teams operating somewhat independently on php.net subprojects. Only a few people are involved in more than one documentation project currently, and that limits the know-how sharing, which would otherwise be possible and desirable. All of the documentation teams use an early fork of the original PHP manual build systems. These systems evolved independently, and took over some improvements fom the others on an occasional basis (the PEAR documentation team uses a variant of the revcheck developed for phpdoc for example). This site is aimed at getting documentation efforts closer, and provide more tools and information for manual authors and translators.
Join us!
The developers of PHP extensions all have access to the PHP documentation modules, although the different projects have different policies of accepting contributions. You are welcome to join our efforts! Authoring documentation for an extension is the second best thing to implementing the extension itself if you are interested in the capabilities, features and usage possibilities even in extreme conditions. We also have translated versions of the different manuals, and most of the translation teams are always in need of more helping hands. In case you are interested, you should contact the relevant mailing lists. The projects and translations have separate mailing lists.
