atom feed28 messages in net.php.lists.phpdoc[PHP-DOC] Getting more people involve...
FromSent OnAttachments
Hannes MagnussonAug 9, 2013 10:34 pm 
Hannes MagnussonAug 9, 2013 10:38 pm.txt
Yasuo OhgakiAug 10, 2013 12:00 am 
Christian WeiskeAug 10, 2013 2:45 am 
Hannes MagnussonAug 10, 2013 12:09 pm 
Nikita PopovAug 10, 2013 12:12 pm 
Levi MorrisonAug 10, 2013 1:15 pm 
Jefersson NathanAug 10, 2013 1:35 pm 
Hannes MagnussonAug 10, 2013 2:04 pm 
Derick RethansAug 12, 2013 1:36 am 
Hannes MagnussonAug 12, 2013 9:47 pm 
Christian StollerAug 12, 2013 11:42 pm 
Stas MalyshevAug 12, 2013 11:48 pm 
Philip OlsonAug 13, 2013 12:00 am 
pedram salehpoorAug 13, 2013 12:18 am 
Hannes MagnussonAug 13, 2013 12:21 am 
Hannes MagnussonAug 13, 2013 12:23 am 
Hannes MagnussonAug 13, 2013 12:31 am 
Nikola SmolenskiAug 13, 2013 2:14 am 
Rafael JaquesAug 13, 2013 10:28 am 
Christian WeiskeAug 13, 2013 9:04 pm 
Nikola SmolenskiAug 13, 2013 11:39 pm 
Jesus M. CastagnettoAug 15, 2013 3:07 pm 
Niel ArcherAug 15, 2013 5:21 pm 
Yannick TorrèsAug 16, 2013 2:45 am 
Derick RethansAug 16, 2013 2:59 am 
Hannes MagnussonAug 16, 2013 12:00 pm 
Richard QuadlingSep 3, 2013 12:09 am 
Subject:[PHP-DOC] Getting more people involved.. bye bye Docbook
From:Hannes Magnusson (hann@gmail.com)
Date:Aug 9, 2013 10:34:22 pm
List:net.php.lists.phpdoc

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