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
