Beautiful! Can we make a copy? Cheers, Marc
On 2011-10-06, at 21.45, Peter Neubauer wrote: > Hi all, > just talked to Niclas about Qi4j and the documentation pains in OSS > projects. Actually, at neo4j.org we bit the bullet to put a REAL > documentation toolchain into place consisting of > Source->Graphviz->AsciiDoc->Docbook->Latex->PDF or -> HTML etc etc. > > What is generated is at http://docs.neo4j.org/chunked/snapshot/ resp > http://neo4j.org/get?file=neo4j-manual-stable.pdf > > See an short example of documentation (documenting a part of the REST > API in a functional test): > > https://github.com/neo4j/cypher-plugin/blob/master/src/test/java/org/neo4j/server/plugin/cypher/CypherPluginFunctionalTest.java#L45 > > results in the docs: > > http://docs.neo4j.org/chunked/snapshot/cypher-plugin.html#rest-api-send-a-query > > > For a more comrehensive example containing a number of code snippets, > formatted output, images (can be of course be replaced by > autogenerated content) and others: > > https://github.com/neo4j/community/blob/master/embedded-examples/src/test/java/org/neo4j/examples/RolesTest.java#L42 > > becomes > > http://docs.neo4j.org/chunked/snapshot/examples-user-roles-in-graphs.html > > The key here is that all code and documentation is kept together as > close as possible, while still making very demanding toolchains like > docbook, that can produce real output like books with crosslinks and > TOC, possible. > > The manual is then assembled, built, versioned and deployed as a first > class citizen together with the build and will stay up to date, since > all moving parts are generated from actually testing code. Try for > instance the different version of > > http://docs.neo4j.org/chunked/snapshot/rest-api-service-root.html > > vs a few versions back, > > http://docs.neo4j.org/chunked/1.4.1/rest-api-service-root.html > > and you will see what I mean. Same goes for the PDF versions. > > So, now the developers actually look into the manual to discover and > check if their stuff looks right. And I am starting to look into what > I call Test Driven Blogging - produce documentation that is as good as > a blog, but will stay up-to-date and get better over time. Look at the > first prototype at > > https://github.com/neo4j/community/blob/master/embedded-examples/src/test/java/org/neo4j/examples/AclExampleTest.java > > Becoming > > http://docs.neo4j.org/chunked/snapshot/examples-acl-structures-in-graphs.html > > This blog is not yet done. Why? Because the last example in Cypher > results in really ugly output. Before tree structures are handled > better, the developers don't want to point people to it. Still, in its > current form, it is accurate and documenting. > > Thought you might be interested. > > Cheers, > > /peter neubauer > > GTalk: neubauer.peter > Skype peter.neubauer > Phone +46 704 106975 > LinkedIn http://www.linkedin.com/in/neubauer > Twitter http://twitter.com/peterneubauer > > http://www.neo4j.org - Your high performance graph database. > http://startupbootcamp.org/ - Öresund - Innovation happens HERE. > http://www.thoughtmade.com - Scandinavia's coolest Bring-a-Thing party. > > _______________________________________________ > qi4j-dev mailing list > [email protected] > http://lists.ops4j.org/mailman/listinfo/qi4j-dev _______________________________________________ qi4j-dev mailing list [email protected] http://lists.ops4j.org/mailman/listinfo/qi4j-dev
