On 10 August 2013 06:34, Hannes Magnusson <hannes.magnus...@gmail.com>wrote:
> Hello > > I've been thinking lately about how we can make it easier for people > to contribute to the project.. > > The OE was a great improvement and made it whole lot simpler to get > going for users and did its job pretty well. > > Editing xml however isn't something the general public seems to be > willing to do, not to mention they have no idea what docbook is at > all. > Other pain points are how long it takes to validate and build the > documentation - and the cheesy tricks we've had to deploy to squeeze > every performance drop out of both PHP and XML. > > > If you guys remember our story.. > DSSSL rendering took _days_ to build. > XSLT took _hours_. > PhD takes _minutes_. > I think we can do better. > I want it down to _seconds_. > > I've been toying with the idea of retiring my baby on its 6year old > birthday early October.. And replace it with something new. Faster. > Easier. Better. > > > I however don't think we can do that with XML. > And I want to make it even easier to contribute - with essentially no > learning curve. > > > Looking around the web.. People seem pretty happy with Markdown... > Now, markdown has its obvious crazy huge drawbacks when it comes to > writing documentations.. but I think it can be done. Well.. Sortof. > > We would need to create our own Markdown flavour, only adding a tick > here and there, should give us very readable format where people focus > on content rather then struggling with picking xml elements or fitting > things into correct containers or limited semantics. > > Rendering our new format into our currently supported formats > shouldn't be a problem, and will more or less be exact same visual > rendering - just massively simplified html output due to the reduction > of the extreme semantics docbook uses. > The important semantics will however still be kept ofcourse. > > > I've already started working on a PhD output format to help with the > transition. > The current format I am targetting looks something like the document > attached. > > > > What do you guys think? :) > > > > -Hannes > I'm not familiar with Markdown at all, but surely there is one documentation standard we should all be aware of as PHP programmers and that's DocBlocks. The argument against changing from something with good semantic markup to purely presentational markdown (from what I've read here - not personal opinion) would suggest to me that we will lose a lot of information. But with DocBlocks, something we should already be using, we can leverage what we already know. And if you all say "WOW! What a great idea!", not only would/could/should phpDocumentor be upgraded to support all the functionality we could want as Documentors, we wouldn't need 2 different engines for PHP documentation. The one that the PHP Documentation Team uses would/could/should also be used by every developer who writes code and uses DocBlocks. OK. AFAICT, DocBlocks are good for documenting code elements/functions/classes/etc. But I think this would be easier to extend to support plain narrative content also. There would need to be a few enhancements to the Reflection API. One that is missing is ReflectionConstant. Currently, no way to access the docblock of a constant - this is a bit of a pain for me as I would like to use constant docblocks to provide additional meta-data in my codebase - coding by documentation (is this annotations ish?). Anyway. I hope that makes some sense - though the reply I got from person off list suggest this isn't viable. Regards, Richard. -- Richard Quadling Twitter : @RQuadling EE : http://e-e.com/M_248814.html Zend : http://bit.ly/9O8vFY
