All documentation should be written in asciidoc - there are lots of resources for that. here's a couple:
http://asciidoc.org/ http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ The asciidoc files are stored with the source code in git in the docs/src/ directory. https://github.com/apache/tinkerpop/tree/master/docs/src I'm not sure where your documentation would fit exactly in that structure just yet, but if you take a look in there you can see how things are organized. You can read a little bit more about this here: http://tinkerpop.apache.org/docs/current/dev/developer/#documentation Is it possible for you to share the documentation you have - in whatever format - so that we can better discuss where it could fit? It might also be better to share before you start doing the conversion just so that everyone on the list can see exactly what the content is to make sure there is consensus that it is suitable for TinkerPop. Obviously, it wouldn't be a great use of your time to do all the asciidoc work and submit a pull request just to have someone say, "Wait a minute...that's not what I thought 'Architectural Best Practice for Graph Database Systems' was going to be!" As part of doing the conversion to asciidoc you will need to setup your local environment to be able to generate the documentation - you can read about that here: http://tinkerpop.apache.org/docs/current/dev/developer/#documentation-environment though you may also use docker: docker/build.sh -d which may be less work. On Thu, Mar 9, 2017 at 6:02 AM, Phil Tetlow <[email protected]> wrote: > Stephen, > > Apologies for the delayed reply. I have a bit of "yes and no" answer for > you. But more "yes" than "no" I feel. The initial idea was to help support > the design and build of solutions, based on graph, from a technology > agnostic perspective. However, we recognise that it is impossible to be > truly agnostic, hence the alignment with this group. So I think it would be > correct to say that, where implementation details need exposing, they > should/will be founded on the Tinkerpop graph stack (as emphasised by the > JanusGraph project http://janusgraph.org/ et al). > > As for your point on documentation style, I agree completely and will > insist that all those who contribute follow the house style. Might you be > able to point me to anything like a style guide please? > > Regards, > > *Dr Phil Tetlow **CEng* > <http://en.wikipedia.org/wiki/Chartered_Engineer_%28UK%29>, *FIET* > <http://www.theiet.org/membership/types/fiet/> > CTO Data Ecosystems, Chief Architect Big Data & Information Management > Products, Adjunt Professor of *Web Science* > <http://en.wikipedia.org/wiki/Web_science>at *Southampton University* > <http://www.southampton.ac.uk/webscience> > (Specialist in *Sociotechnical Systems* > <http://en.wikipedia.org/wiki/Sociotechnical_system> & Reflective > Engineering) > Executive IT Architect, *IBM Academy of Technology* > <http://www.ibm.com/ibm/academy> (Leadership Team) & *W3C* > <http://www.w3.org/> Member > IBM Analytics Division > ------------------------------ > *Phone:* 44-7740-923328 | *Mobile:* 44-7740-923328 (262999) > * E-mail:* *[email protected]* <[email protected]> > * Find me on:* [image: LinkedIn:] > <http://uk.linkedin.com/pub/phil-tetlow/3/b59/668/>*LinkedIn* > <http://uk.linkedin.com/pub/phil-tetlow/3/b59/668/> [image: Twitter:] > <https://twitter.com/DocPhilT>*Twitter* <https://twitter.com/DocPhilT> * > More on: **Web Science * <http://en.wikipedia.org/wiki/Web_science>*| **Power > Laws* <http://en.wikipedia.org/wiki/Power_laws>| *Mements* > * My Books :* [image: LinkedIn:]*The Web's Awake* > <http://www.amazon.co.uk/The-Webs-Awake-Introduction-Science/dp/0470137940/ref=sr_1_1?ie=UTF8&qid=1394442305&sr=8-1&keywords=Philip%2BTetlow> > [image: > Twitter:]*Understanding Information and Computation* > <http://www.amazon.co.uk/Understanding-Information-Computation-Philip-Tetlow/dp/1409440397/ref=sr_1_2?ie=UTF8&qid=1394442305&sr=8-2&keywords=Philip%2BTetlow> > *Personal > Web Site* > [image: IBM] > > 1175 Century Way > Leeds, LS15 8ZB > United Kingdom > > > > > > > > From: Stephen Mallette <[email protected]> > To: [email protected], Phil Tetlow/UK/IBM@IBMGB > Date: 02/02/2017 17:10 > Subject: Re: Architectural Best Practice for Graph Database Systems > ------------------------------ > > > > I think TinkerPop has most of its documentation focused on TinkerPop > itself which is a pretty big topic and less on "how to implement > applications with TinkerPop". I think the community could benefit from > documentation like that. Is that what the content you have is about when > you refer to "Architectural Best Practice for Graph Database Systems"? > > Just a personal opinion, but I will say that TinkerPop does have a certain > style to its documentation, its web site, etc. I'd personally like to see > all documentation fit that style, so depending on what's been written, it > might need some tweaking to make it fit the model that's been established > here. > > That's about all I can say at the moment without more information about > what you currently have that you'd like to contribute. Perhaps you could > provide some more information about it. > > On Thu, Feb 2, 2017 at 11:54 AM, Phil Tetlow <*[email protected]* > <[email protected]>> wrote: > All, > > IBM has been working on graph database for some time (culminating in > JanusGraph, a new community project under The Linux Foundation ) and has > amassed lots of best practice in this area. We have also looked at a number > of technology stacks, but now are settling on Titan and Tinkerpop as our > standard - thereby offering native integration as an integral feature of > Janus. > > Of late we have noticed a growing interest in graph database and we are > excited about the level of contribution through mailing lists like this. > That said, we have also noticed a distinct lack of shared insight into how > best to design and build systems using graph, and we would be interested to > hear if those on this list agree? We have been referring to this as > “Architectural Best Practice for Graph Database Systems” and we already > have a number of assets we would like to share openly. That presents a > challenge, however, as currently we see no natural home for such materials > within the open source community. Nevertheless, when we thought about it, > the clear consensus pointed to some branch under Tinkerpop, and for this > reason we are reaching out to understand if and how best to proceed? > > Those interested from IBM will be watching this list with keen interest , > but to get immediate feedback I would be grateful if you could copy to > *[email protected]* <[email protected]>. > > Many thanks indeed and we look forward to hearing from you. > > Regards, > > * Dr Phil Tetlow **CEng* > <http://en.wikipedia.org/wiki/Chartered_Engineer_%28UK%29>, *FIET* > <http://www.theiet.org/membership/types/fiet/> > CTO Data Ecosystems, Chief Architect Big Data & Information Management > Products, Adjunt Professor of *Web Science* > <http://en.wikipedia.org/wiki/Web_science>at *Southampton University* > <http://www.southampton.ac.uk/webscience> > (Specialist in *Sociotechnical Systems* > <http://en.wikipedia.org/wiki/Sociotechnical_system> & Reflective > Engineering) > Executive IT Architect, *IBM Academy of Technology* > <http://www.ibm.com/ibm/academy> (Leadership Team) & *W3C* > <http://www.w3.org/> Member > IBM Analytics Division > ------------------------------ > *Phone:* 44-7740-923328 | *Mobile:* 44-7740-923328 (262999) > * E-mail:* *[email protected]* <[email protected]> > * Find me on:* <http://uk.linkedin.com/pub/phil-tetlow/3/b59/668/> > *LinkedIn* <http://uk.linkedin.com/pub/phil-tetlow/3/b59/668/> > <https://twitter.com/DocPhilT>*Twitter* <https://twitter.com/DocPhilT> * > More on: **Web Science * <http://en.wikipedia.org/wiki/Web_science>*| **Power > Laws* <http://en.wikipedia.org/wiki/Power_laws>| *Mements* > * My Books :* *The Web's Awake* > <http://www.amazon.co.uk/The-Webs-Awake-Introduction-Science/dp/0470137940/ref=sr_1_1?ie=UTF8&qid=1394442305&sr=8-1&keywords=Philip%2BTetlow> > *Understanding > Information and Computation* > <http://www.amazon.co.uk/Understanding-Information-Computation-Philip-Tetlow/dp/1409440397/ref=sr_1_2?ie=UTF8&qid=1394442305&sr=8-2&keywords=Philip%2BTetlow> > *Personal > Web Site* > > > 1175 Century Way > Leeds, LS15 8ZB > United Kingdom > > > > > > Unless stated otherwise above: > IBM United Kingdom Limited - Registered in England and Wales with number > 741598. > Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU > > > > Unless stated otherwise above: > IBM United Kingdom Limited - Registered in England and Wales with number > 741598. > Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU >
