On Wed, Jan 19, 2011 at 16:32, Cheetham, Anastasia <acheet...@ocad.ca> wrote: > > Hello, > > My name is Anastasia Cheetham. I'm a developer with and the documentation > lead for the Fluid Project (http://fluidproject.org). We're beginning the > process of restructuring and redesigning the documentation for our Infusion > framework. Part of that process will include migrating to a new platform for > the creation and distribution of documentation, and we're interested in > learning about the experiences of other open source projects, including PHP. > > I've had a look at you How To pages for contributing documentation, and I see > that you use DocBook. I'd be interested in hearing your thoughts on DocBook: > > - What do you feel are its strengths? What are its weaknesses?
DocBook is the language of choice when it comes to computer related papers, books, docs, etc etc. It offers a great set of specifically tailor sementic elements for various software, and hardware, things. The "todays" weakness of DocBook is.. the same as their strong parts. In the phpdoc project why provide quite explicit skeletons for various things. The primary reasons behind that is obviously consistency (both for rendering and structure), but also for simplicity for new documentors. Docbook has a massive amount of elements, many of which are completely irrelevant for your task - so why bother teaching new people 500 new things when she really only needs to know 12 elements? We do however not restrict our schema (although we could with DocBook5 quite easily), since we do want to make it possible for experienced Docbook users to create great things for special cases. > > - How easy or hard it is to customize the look and feel of the interface with > DocBook? i.e. style, layout, navigation, etc. > Superdupermegaultra easy. In our specific case, we had so many custom rendering needs that using the standard DocBook-XSL stylesheets become very slow for us.. so.. we create our own DocBook rendering engine, called; PhD. PhD is written in PHP and is (in my, very not objective opinion) redonkylously easy to extend and customize. Everything on http://php.net/manual is generated by PhD.. Everything on http://www.docbook.org/tdg51/en/html/docbook.html is generated by Docbook-XSL Costumizing the "look and feel" is the least of your problems. DocBook is not only especially well suited for html generation, generating unix man pages is really easy (and very natural), pdf, chm, ..., most formats you can dream of is a second nature to DocBook and most of its rendering applications. As for navigation, in the case of phpdocs - we follow prettymuch the "defaults" from DocBook-XSL (most of PhD does - as it originally was designed to just be 3750% faster alternative to Docbook-XSL), but we do some "cheats". We for example index the entire document and store the index in a .sqlite, making all sort of tricks and tips possible. > - Do you use any form of auto-generated API documentation? If so, how to you > manage integration with more narrative text such as tutorials, etc? > Sorry.. Its late on Friday.. I haven't researches your project enough to understand your needs.. We have autogenerated *skeletons* for APIs (the phpdocs are just API docs.. with random other content). Those skeletons provide basic information behind the API, but it requires a lot of manual work to actually document things. The PHP-GTK guys are working on some extra superduper autogeneration.. But seriously, is that something you really want to feed to your users? Autogenerated random "crap"? If you won't take the time to write it, why should the users take the time to read it? > > I thank you very much for your time, and for any thoughts you can share. So.. Sorry for the late answer.. It is however late on a Friday.. I may have missed couple of points, or not explained things enough.. Feel free to ask again/follow up questions, or contact us with your plans :] The DocBook guys are relatively active on their lists, both on docbook@ and on docbook-apps@ (@lists.oasis-open.org), if want to checkin on them. Docbook is "kindof" an OSS project, so its fine to ask them for help, especially when/if you start design skeletons for your project. And at last, a shameless plug: PhD (The "[PH]P based [D]ocbook renderer) is used by several projects, and is maintained by the PHP.net project. Since its relatively young project (2-3 years old), getting changes to it is very easy - and creating totally new packages is even easier. -Hannes
