I've been thinking about documentation a bit. I don't think folks are aware
of all the documentation that we have. The typical example is the IO
Reference docs which no one every seems to find:

http://tinkerpop.apache.org/docs/current/dev/io

I long ago added this documentation landing page:

http://tinkerpop.apache.org/docs/current

which I also think no one really knows about, but it lists all of our
documentation and puts it all into categories. I've updated that a few
moments ago a little bit (but have not yet published) with a few more
changes to come:

https://github.com/apache/tinkerpop/commit/0108bfcc0c1646e23a92a459f12dd8f48b80a233

I think we should make this "Compendium" page more the focus of where folks
go to get documentation. That would mean:

1. On the TinkerPop home page, remove "Tutorials" and "Publications"
sections - right now they are in sync with the Compendium. I sense we're
missing a few useful publications there. It might also be nice to offer a
better explanation of what each publication is and why a user would want to
read them. "Graphendodonticology" is an awesome post, but the title really
doesn't give anyone a hint as to why they would want to click on it. We
can't really do that now on the home page without blowing it out super long.
2. Change the "Documentation" section on the home page to basically look
like this:

* TinkerPop Documentation
** Reference Documentation
* Upgrade Documentation
* Javadoc - [core] / [full]

So basically, the first bullet above will go to the compendium. The rest of
the links should be self-explanatory.
3. Change the Documentation/Publications to link to the
Compendium#Publications

Any thoughts on the matter?

Reply via email to