I'm totally in agreement here, and I would add to the list the migration from the wiki to the site-book. There were some prior email conversations on this, some of which I started and then didn't follow up on, but I see this as pretty important and I'm still interested in doing the work/helping as time allows.
Jon On Thu, Jul 27, 2017 at 10:48 AM Justin Leet <[email protected]> wrote: > I wanted to start a discussion and get some thoughts on what some of the > hurdles are to contributing and working on contributions. I'd like to make > it easier for everyone to dive right in and make contributions throughout > the project (and even just get information about what we're building). > > We've been incrementally working on this with some great stuff (The site > book, perf tuning guide, some cleanup around organization, etc.) and it'd > be nice to keep that momentum going. > > Here's a couple things off the top of my head that I thought of. Feel free > to expand, agree, disagree, etc.: > > - Link the site-book more prominently, probably on the GitHub landing > page. It takes a few hops to find right now (or I'm not finding the > right > hops, which is its own potential hurdle). > - In the same vein, link to the contributing docs on the main landing > README. It should be immediately obvious where to go to start being > able to > contribute. > - Improve our Javadocs and general Maven reporting and make them more > generally discoverable? I know a lot of this is continually in flux as > we've been building and improving even foundational things, so we'd > probably want to be careful about how much we want to do here. > - Improve Ambari dev docs. I started that with ( > https://github.com/apache/metron/pull/673), but I know there's more to > flesh out there. Feel free to hop on the comments of that. I'd love to > hear > what first impression hurdles are, even (especially?) if you haven't > touched mpack) > - Guides on debugging. We've been doing a couple things, but we need to > make it easier to find and diagnose problems, imo. A lot of this is > debugging of our dependencies, but ultimately we need to at least give a > starting point into digging into that type of thing. > - We've been improving the "How do I just spin something up and see it > work" experience and decreasing confusion around options, but I'm sure > there's more we can do here (Suggestions?) > - Tribal knowledge in general. I'd list specifics, but I don't know > them because they aren't documented. > > I'd love to see this list expanded with thoughts and even tickets. > -- Jon
