You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tinkerpop.apache.org by Stephen Mallette <sp...@gmail.com> on 2017/08/09 15:15:26 UTC
[DISCUSS] Documentation Organization
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?
Re: [DISCUSS] Documentation Organization
Posted by Stephen Mallette <sp...@gmail.com>.
I finally got a run of tp32 to build (and publish) after days of hanging in
giraph. I don't know how it suddenly started working but it did. I have no
idea yet if it is consistently working. master is still failing....it just
hangs and the hadoop logs just fill indefinitely with:
2017-08-15 21:55:30,699 INFO [IPC Server handler 23 on 33500]
org.apache.hadoop.mapred.TaskAttemptListenerImpl: Progress of TaskAttempt
attempt_1502824851008_0007_m_000001_0 is : 1.0
2017-08-15 21:55:33,743 INFO [IPC Server handler 18 on 33500]
org.apache.hadoop.mapred.TaskAttemptListenerImpl: Progress of TaskAttempt
attempt_1502824851008_0007_m_000001_0 is : 1.0
2017-08-15 21:55:36,776 INFO [IPC Server handler 19 on 33500]
org.apache.hadoop.mapred.TaskAttemptListenerImpl: Progress of TaskAttempt
attempt_1502824851008_0007_m_000001_0 is : 1.0
2017-08-15 21:55:38,923 INFO [IPC Server handler 14 on 33500]
org.apache.hadoop.mapred.TaskAttemptListenerImpl: Progress of TaskAttempt
attempt_1502824851008_0007_m_000002_0 is : 1.0
...
It fails for both local doc generation and in docker. It also fails the
same way if you execute a giraph job on its own from the console. I asked
Ted to run docs since tp31 published fine for him (and for me). On his
system tp32 generated through giraph then died in gremlin-python using
docker. Kuppitz and I have had largely the same build problems on both
branches. Ultimately, this must be something environmental (though docker
should be the great equalizer) with hadoop....but I'm not sure what. I
suppose if you (or anyone else) can spare some processing today, see if you
can generate docs on tp32 or master and let me know your findings.
On Tue, Aug 15, 2017 at 11:27 PM, Robert Dale <ro...@gmail.com> wrote:
> Anything you need help with?
>
> Robert Dale
>
> On Tue, Aug 15, 2017 at 8:22 PM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > yes - i didn't see any objections or other suggestions so I moved with
> what
> > I proposed. pretty minor differences but i think it's an improvement. i'd
> > like to work on the publications section a bit but we're still
> semi-jammed
> > with doc generation problems atm.
> >
> > On Tue, Aug 15, 2017 at 8:06 PM, Robert Dale <ro...@gmail.com> wrote:
> >
> > > I see changes. I guess the 72 hours is up!
> > >
> > > Robert Dale
> > >
> > > On Wed, Aug 9, 2017 at 11:15 AM, Stephen Mallette <
> spmallette@gmail.com>
> > > wrote:
> > >
> > > > 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/
> > > 0108bfcc0c1646e23a92a459f12dd8
> > > > f48b80a233
> > > >
> > > > 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?
> > > >
> > >
> >
>
Re: [DISCUSS] Documentation Organization
Posted by Robert Dale <ro...@gmail.com>.
Anything you need help with?
Robert Dale
On Tue, Aug 15, 2017 at 8:22 PM, Stephen Mallette <sp...@gmail.com>
wrote:
> yes - i didn't see any objections or other suggestions so I moved with what
> I proposed. pretty minor differences but i think it's an improvement. i'd
> like to work on the publications section a bit but we're still semi-jammed
> with doc generation problems atm.
>
> On Tue, Aug 15, 2017 at 8:06 PM, Robert Dale <ro...@gmail.com> wrote:
>
> > I see changes. I guess the 72 hours is up!
> >
> > Robert Dale
> >
> > On Wed, Aug 9, 2017 at 11:15 AM, Stephen Mallette <sp...@gmail.com>
> > wrote:
> >
> > > 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/
> > 0108bfcc0c1646e23a92a459f12dd8
> > > f48b80a233
> > >
> > > 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?
> > >
> >
>
Re: [DISCUSS] Documentation Organization
Posted by Stephen Mallette <sp...@gmail.com>.
yes - i didn't see any objections or other suggestions so I moved with what
I proposed. pretty minor differences but i think it's an improvement. i'd
like to work on the publications section a bit but we're still semi-jammed
with doc generation problems atm.
On Tue, Aug 15, 2017 at 8:06 PM, Robert Dale <ro...@gmail.com> wrote:
> I see changes. I guess the 72 hours is up!
>
> Robert Dale
>
> On Wed, Aug 9, 2017 at 11:15 AM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > 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/
> 0108bfcc0c1646e23a92a459f12dd8
> > f48b80a233
> >
> > 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?
> >
>
Re: [DISCUSS] Documentation Organization
Posted by Robert Dale <ro...@gmail.com>.
I see changes. I guess the 72 hours is up!
Robert Dale
On Wed, Aug 9, 2017 at 11:15 AM, Stephen Mallette <sp...@gmail.com>
wrote:
> 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/0108bfcc0c1646e23a92a459f12dd8
> f48b80a233
>
> 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?
>