Site organization, including links to recipes and various tutorials

[Jeremy Hanna <je...@gmail.com>]

I’ve given the links to the recipes page and the getting started tutorial (for instance) to people and they’ve said, “hey wow, this is great stuff.  I wish I had this like last week!”  I see that the only place those are currently is the TinkerPop home page.  So I wondered what a better place for those would be.  Should we put them near the top of the docs page as well?  Any thoughts on perhaps reorganizing the home page?

Thanks,

Jeremy

Re: Site organization, including links to recipes and various tutorials

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

It took me a a while but I figured out how to inject the project version
from the maven pom directly into javadoc. I guess the approach ended up
being pretty simple and just uses filtering with the maven resources
plugin, but it seemed like a hacky way to implement it. I thought for sure
there would be something built directly into the maven javadoc plugin, but
sadly I could come up with no such solution. Anyway, this change lets us to
better cross-reference our javadoc with our reference docs which is
something we've ignored a bit (mostly because we've never had this nice way
to link to those documents without the "version variable").

I've started to complete the javadoc on GraphTraversal and cross-reference
that to the reference docs with @see tags. If you ever feel the need to
link from javadoc to the Reference Docs you can see the pattern that I've
started in GraphTraversal at this point on the tp32/mastter branch. I still
have a little ways to go with GraphTraversal to get that all javadoc'd - i
suspect I might finish a rough pass at it all by end of day tomorrow.

On Thu, Feb 9, 2017 at 1:28 PM, Stephen Mallette <sp...@gmail.com>
wrote:

> One idea I've had is to better cross reference our docs. More links
> between the different documents we have would be helpful. For example, when
> we mention a particular step somewhere in a recpie or tutorial, do a link
> to the step in the reference docs. For each step in the reference docs have
> a "See also" section that links to other areas in tutorials, recipes, etc.
> where that step is used. I think that would get people more aware of what's
> out there and would give them the chance to read more of what we have
> available.  It does represent a fair bit of work though.
>
> I don't doubt that we couldn't improve the web site. Would be nice to hear
> if anyone has specific proposals in that area.
>
> On Thu, Feb 9, 2017 at 1:16 PM, Jeremy Hanna <je...@gmail.com>
> wrote:
>
>> I’ve given the links to the recipes page and the getting started tutorial
>> (for instance) to people and they’ve said, “hey wow, this is great stuff.
>> I wish I had this like last week!”  I see that the only place those are
>> currently is the TinkerPop home page.  So I wondered what a better place
>> for those would be.  Should we put them near the top of the docs page as
>> well?  Any thoughts on perhaps reorganizing the home page?
>>
>> Thanks,
>>
>> Jeremy
>
>
>

Re: Site organization, including links to recipes and various tutorials

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

One idea I've had is to better cross reference our docs. More links between
the different documents we have would be helpful. For example, when we
mention a particular step somewhere in a recpie or tutorial, do a link to
the step in the reference docs. For each step in the reference docs have a
"See also" section that links to other areas in tutorials, recipes, etc.
where that step is used. I think that would get people more aware of what's
out there and would give them the chance to read more of what we have
available.  It does represent a fair bit of work though.

I don't doubt that we couldn't improve the web site. Would be nice to hear
if anyone has specific proposals in that area.

On Thu, Feb 9, 2017 at 1:16 PM, Jeremy Hanna <je...@gmail.com>
wrote:

> I’ve given the links to the recipes page and the getting started tutorial
> (for instance) to people and they’ve said, “hey wow, this is great stuff.
> I wish I had this like last week!”  I see that the only place those are
> currently is the TinkerPop home page.  So I wondered what a better place
> for those would be.  Should we put them near the top of the docs page as
> well?  Any thoughts on perhaps reorganizing the home page?
>
> Thanks,
>
> Jeremy