VertexProgram Documentation

[Stephen Mallette <sp...@gmail.com>]

I was looking at the Guru's PR for shortestPath() and noticed that he
followed our pattern for VertexPrograms and added this:

https://github.com/apache/tinkerpop/pull/882/files#diff-39035762ba5b6c0cc9c54828dec80c40

We can leave this here for now for purpose of the PR , but it raised
something in my mind....i think we should move much of the `GraphComputer`
section out of the reference documentation. Users are going to use the
various Gremlin steps we expose for this and we likely don't want them
getting confused by any of this way of configuring these things (especially
since they don't work in GLVs).  I think I'm going to re-work this section
to a "tutorial" or perhaps even dev docs - not sure which.

Ultimately, I think reference docs should be for users of the Gremlin
language and anything that is not a "Gremlin oriented" way of doing things
should be extracted elsewhere.

Re: VertexProgram Documentation

[Stephen Mallette <sp...@gmail.com>]

I'm still against fully splitting the documentation just yet. I'm more in
favor of a unified and cohesive document set. I still think that can be
achieved with a lot of work, but if that somehow fails, then maybe breaking
them apart is necessary. That said, just breaking them apart along those
sections that you describe doesn't really solve the "problem" in my mind.
There has to be something that connects these concepts together across all
those separate docs - imo, that task is harder when separated and easier
when kept together.

I picked on GraphComputer because it's an easy one. Can't do it with pure
Gremlin? Should't be in the primary reference documentation. Easy rule.

On Thu, Aug 2, 2018 at 9:10 AM <fh...@florian-hockmann.de> wrote:

> I already proposed this at another occasion, but I think it would also be
> a possible solution for this “problem”: Couldn’t we simply split our
> reference documentation into different sites for different purposes? In the
> long term, I could imagine a division roughly like this:
> • Gremlin language reference documentation
> • Gremlin Server
> • Gremlin Console
> • OLAP / Graph Computer
> • GLVs + language drivers
>
> I’m not saying that we should split up the docs completely like this
> immediately but a first step in this direction could be to now create
> another documentation for the GraphComputer part.
>
> -----Ursprüngliche Nachricht-----
> Von: Stephen Mallette <sp...@gmail.com>
> Gesendet: Donnerstag, 2. August 2018 13:07
> An: dev@tinkerpop.apache.org
> Betreff: VertexProgram Documentation
>
> I was looking at the Guru's PR for shortestPath() and noticed that he
> followed our pattern for VertexPrograms and added this:
>
>
> https://github.com/apache/tinkerpop/pull/882/files#diff-39035762ba5b6c0cc9c54828dec80c40
>
> We can leave this here for now for purpose of the PR , but it raised
> something in my mind....i think we should move much of the `GraphComputer`
> section out of the reference documentation. Users are going to use the
> various Gremlin steps we expose for this and we likely don't want them
> getting confused by any of this way of configuring these things (especially
> since they don't work in GLVs).  I think I'm going to re-work this section
> to a "tutorial" or perhaps even dev docs - not sure which.
>
> Ultimately, I think reference docs should be for users of the Gremlin
> language and anything that is not a "Gremlin oriented" way of doing things
> should be extracted elsewhere.
>
>

AW: VertexProgram Documentation

[fh...@florian-hockmann.de]

I already proposed this at another occasion, but I think it would also be a possible solution for this “problem”: Couldn’t we simply split our reference documentation into different sites for different purposes? In the long term, I could imagine a division roughly like this:
• Gremlin language reference documentation
• Gremlin Server
• Gremlin Console
• OLAP / Graph Computer
• GLVs + language drivers

I’m not saying that we should split up the docs completely like this immediately but a first step in this direction could be to now create another documentation for the GraphComputer part.

-----Ursprüngliche Nachricht-----
Von: Stephen Mallette <sp...@gmail.com> 
Gesendet: Donnerstag, 2. August 2018 13:07
An: dev@tinkerpop.apache.org
Betreff: VertexProgram Documentation

I was looking at the Guru's PR for shortestPath() and noticed that he followed our pattern for VertexPrograms and added this:

https://github.com/apache/tinkerpop/pull/882/files#diff-39035762ba5b6c0cc9c54828dec80c40

We can leave this here for now for purpose of the PR , but it raised something in my mind....i think we should move much of the `GraphComputer` section out of the reference documentation. Users are going to use the various Gremlin steps we expose for this and we likely don't want them getting confused by any of this way of configuring these things (especially since they don't work in GLVs).  I think I'm going to re-work this section to a "tutorial" or perhaps even dev docs - not sure which.

Ultimately, I think reference docs should be for users of the Gremlin language and anything that is not a "Gremlin oriented" way of doing things should be extracted elsewhere.