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 <[email protected]> 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 <[email protected]> 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 <[email protected]>
>> 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.
>>
