Documentation and thoughts on getting started

[Aldrin Piri <al...@gmail.com>]

Hey folks,

Long time lurker, first time emailer.  In my free time, I've done several
cursory, albeit brief, explorations with Yetus to help out our reviewing
efforts and reduce time to merge, but got a bit lost figuring out where to
dig in.  I will frame the this note by saying that I am not deep into the
Hadoop ecosystem as a whole, so some level of knowledge or experiences that
others may have could be absent.

I had the opportunity to attend Allen's Yetus talk today at ApacheCon Big
Data (great job! would be great to see some of these items make their way
onto the site when available) which most certainly helped illuminate a
couple of points for me.  Coming to the project with some guiding insights
from a few folks I talked to, my impression was a kind of "ecosystem of
components."  To further clarify, it seemed like each component was kind of
dependent on the others and there was a full package of functionality.
Allen's sweet architecture diagram kind of put things into perspective for
me and cleared up that there are a few different personas and the various
components cater to different audiences.

* Precommit for those handling patch review
* Release Doc maker for the RM
* Shelldoc for those people/projects doing scripting in their project
efforts to generate Javadoc like functionality
* Audience Annotations for those designing APIs and extension points.

In full disclosure, this is all quite obvious to me in light of the talk
but things did not quite mesh viewing the docs in isolation or without
sufficient attention.  A quick start or similar that lets folks self select
for certain roles could be quite nice, something akin to:

* "I'm a code reviewer and would like to avoid the motions of commit
monotony.",
* "I'm an RM and my project needs great release notes.",
* "I'm a developer and want my program to be extensible but have certain
caveats about some areas.",
and so on.

Again, nice work on the presentation today and on the efforts of the
project.

Re: Documentation and thoughts on getting started

[Allen Wittenauer <aw...@apache.org>]

	Hey thanks!

	This is all tremendous feedback!

	I really like the idea of quickstart guides for specific tasks and I think that would go a long way to resolving a lot of the confusion that I heard from a lot of people over the past few days.

	One of the original ideas I had for the website was to actually have big buttons on the front page that linked to specific functionality underneath the large Apache Yetus definition.  I don’t remember why I threw it out, but I think it might have been because we didn’t have documentation for everything yet!  I think it’s time to revisit that, but instead of linking to tools, linking to how-to guides for those tools (secretly hidden as tasks) might be the way to do it.


> On May 11, 2016, at 2:41 PM, Aldrin Piri <al...@gmail.com> wrote:
> 
> I think the structure is there, just some niceties would be great as an
> initial effort and "coming soon" approach.
> 
> For the sake of clarity, I almost see it as being less of a snapshot of
> Yetus' functionality and more focusing on highlighting its value and/or
> more pointed use cases that route people to the appropriate component.
> Specific guides would also be nice, but could certainly be provided at a
> later juncture. Yetus is the project, but each of those individual items
> can stand on its own with its own value.  Allen joked about his
> architecture diagram, but that in conjunction with the talk of Yetus being
> the driver for each of these items was helpful  (although, in the current
> state, audience-annotations may be a bit outside of this illustration).
> 
> Unfortunately, I am no longer able to un-see now that it has registered and
> am having a hard time articulating.
> 
> On Wed, May 11, 2016 at 5:15 PM, Sean Busbey <bu...@apache.org> wrote:
> 
>> Thanks for taking the time to give us feedback Aldrin!
>> 
>> Quickstart guides would be a great addition; I hadn't thought of
>> taking the "As a X I want foo" approach to organizing them.
>> 
>> Would it be useful for us to start sketching out the structure of
>> those audience-centric guides before any/all of them exist? or would
>> what are effectively "coming soon" markers be more likely to turn
>> folks away rather than spur contributions to fill the gaps?
>> 
>> On Wed, May 11, 2016 at 12:29 PM, Aldrin Piri <al...@gmail.com>
>> wrote:
>>> Hey folks,
>>> 
>>> Long time lurker, first time emailer.  In my free time, I've done several
>>> cursory, albeit brief, explorations with Yetus to help out our reviewing
>>> efforts and reduce time to merge, but got a bit lost figuring out where
>> to
>>> dig in.  I will frame the this note by saying that I am not deep into the
>>> Hadoop ecosystem as a whole, so some level of knowledge or experiences
>> that
>>> others may have could be absent.
>>> 
>>> I had the opportunity to attend Allen's Yetus talk today at ApacheCon Big
>>> Data (great job! would be great to see some of these items make their way
>>> onto the site when available) which most certainly helped illuminate a
>>> couple of points for me.  Coming to the project with some guiding
>> insights
>>> from a few folks I talked to, my impression was a kind of "ecosystem of
>>> components."  To further clarify, it seemed like each component was kind
>> of
>>> dependent on the others and there was a full package of functionality.
>>> Allen's sweet architecture diagram kind of put things into perspective
>> for
>>> me and cleared up that there are a few different personas and the various
>>> components cater to different audiences.
>>> 
>>> * Precommit for those handling patch review
>>> * Release Doc maker for the RM
>>> * Shelldoc for those people/projects doing scripting in their project
>>> efforts to generate Javadoc like functionality
>>> * Audience Annotations for those designing APIs and extension points.
>>> 
>>> In full disclosure, this is all quite obvious to me in light of the talk
>>> but things did not quite mesh viewing the docs in isolation or without
>>> sufficient attention.  A quick start or similar that lets folks self
>> select
>>> for certain roles could be quite nice, something akin to:
>>> 
>>> * "I'm a code reviewer and would like to avoid the motions of commit
>>> monotony.",
>>> * "I'm an RM and my project needs great release notes.",
>>> * "I'm a developer and want my program to be extensible but have certain
>>> caveats about some areas.",
>>> and so on.
>>> 
>>> Again, nice work on the presentation today and on the efforts of the
>>> project.
>> 

Re: Documentation and thoughts on getting started

[Aldrin Piri <al...@gmail.com>]

I think the structure is there, just some niceties would be great as an
initial effort and "coming soon" approach.

For the sake of clarity, I almost see it as being less of a snapshot of
Yetus' functionality and more focusing on highlighting its value and/or
more pointed use cases that route people to the appropriate component.
Specific guides would also be nice, but could certainly be provided at a
later juncture. Yetus is the project, but each of those individual items
can stand on its own with its own value.  Allen joked about his
architecture diagram, but that in conjunction with the talk of Yetus being
the driver for each of these items was helpful  (although, in the current
state, audience-annotations may be a bit outside of this illustration).

Unfortunately, I am no longer able to un-see now that it has registered and
am having a hard time articulating.

On Wed, May 11, 2016 at 5:15 PM, Sean Busbey <bu...@apache.org> wrote:

> Thanks for taking the time to give us feedback Aldrin!
>
> Quickstart guides would be a great addition; I hadn't thought of
> taking the "As a X I want foo" approach to organizing them.
>
> Would it be useful for us to start sketching out the structure of
> those audience-centric guides before any/all of them exist? or would
> what are effectively "coming soon" markers be more likely to turn
> folks away rather than spur contributions to fill the gaps?
>
> On Wed, May 11, 2016 at 12:29 PM, Aldrin Piri <al...@gmail.com>
> wrote:
> > Hey folks,
> >
> > Long time lurker, first time emailer.  In my free time, I've done several
> > cursory, albeit brief, explorations with Yetus to help out our reviewing
> > efforts and reduce time to merge, but got a bit lost figuring out where
> to
> > dig in.  I will frame the this note by saying that I am not deep into the
> > Hadoop ecosystem as a whole, so some level of knowledge or experiences
> that
> > others may have could be absent.
> >
> > I had the opportunity to attend Allen's Yetus talk today at ApacheCon Big
> > Data (great job! would be great to see some of these items make their way
> > onto the site when available) which most certainly helped illuminate a
> > couple of points for me.  Coming to the project with some guiding
> insights
> > from a few folks I talked to, my impression was a kind of "ecosystem of
> > components."  To further clarify, it seemed like each component was kind
> of
> > dependent on the others and there was a full package of functionality.
> > Allen's sweet architecture diagram kind of put things into perspective
> for
> > me and cleared up that there are a few different personas and the various
> > components cater to different audiences.
> >
> > * Precommit for those handling patch review
> > * Release Doc maker for the RM
> > * Shelldoc for those people/projects doing scripting in their project
> > efforts to generate Javadoc like functionality
> > * Audience Annotations for those designing APIs and extension points.
> >
> > In full disclosure, this is all quite obvious to me in light of the talk
> > but things did not quite mesh viewing the docs in isolation or without
> > sufficient attention.  A quick start or similar that lets folks self
> select
> > for certain roles could be quite nice, something akin to:
> >
> > * "I'm a code reviewer and would like to avoid the motions of commit
> > monotony.",
> > * "I'm an RM and my project needs great release notes.",
> > * "I'm a developer and want my program to be extensible but have certain
> > caveats about some areas.",
> > and so on.
> >
> > Again, nice work on the presentation today and on the efforts of the
> > project.
>

Re: Documentation and thoughts on getting started

[Sean Busbey <bu...@apache.org>]

Thanks for taking the time to give us feedback Aldrin!

Quickstart guides would be a great addition; I hadn't thought of
taking the "As a X I want foo" approach to organizing them.

Would it be useful for us to start sketching out the structure of
those audience-centric guides before any/all of them exist? or would
what are effectively "coming soon" markers be more likely to turn
folks away rather than spur contributions to fill the gaps?

On Wed, May 11, 2016 at 12:29 PM, Aldrin Piri <al...@gmail.com> wrote:
> Hey folks,
>
> Long time lurker, first time emailer.  In my free time, I've done several
> cursory, albeit brief, explorations with Yetus to help out our reviewing
> efforts and reduce time to merge, but got a bit lost figuring out where to
> dig in.  I will frame the this note by saying that I am not deep into the
> Hadoop ecosystem as a whole, so some level of knowledge or experiences that
> others may have could be absent.
>
> I had the opportunity to attend Allen's Yetus talk today at ApacheCon Big
> Data (great job! would be great to see some of these items make their way
> onto the site when available) which most certainly helped illuminate a
> couple of points for me.  Coming to the project with some guiding insights
> from a few folks I talked to, my impression was a kind of "ecosystem of
> components."  To further clarify, it seemed like each component was kind of
> dependent on the others and there was a full package of functionality.
> Allen's sweet architecture diagram kind of put things into perspective for
> me and cleared up that there are a few different personas and the various
> components cater to different audiences.
>
> * Precommit for those handling patch review
> * Release Doc maker for the RM
> * Shelldoc for those people/projects doing scripting in their project
> efforts to generate Javadoc like functionality
> * Audience Annotations for those designing APIs and extension points.
>
> In full disclosure, this is all quite obvious to me in light of the talk
> but things did not quite mesh viewing the docs in isolation or without
> sufficient attention.  A quick start or similar that lets folks self select
> for certain roles could be quite nice, something akin to:
>
> * "I'm a code reviewer and would like to avoid the motions of commit
> monotony.",
> * "I'm an RM and my project needs great release notes.",
> * "I'm a developer and want my program to be extensible but have certain
> caveats about some areas.",
> and so on.
>
> Again, nice work on the presentation today and on the efforts of the
> project.