Hi Susan, Super excited about your interest in Sentry. Our docs are definitely an area that could use some love and could have a huge impact on the project. How would you prefer to get started? Happy to answer your questions via e-mail, or if you prefer we could also setup a google hangouts meeting so you can get introduced some committers and answer questions "in person".
Thanks, Lenni On Tue, Oct 13, 2015 at 8:33 AM, Susan Lauber <[email protected]> wrote: > Greetings, > > I am excited to dig into a new opensource project. > I am still digging through the documentation that does exist on the wiki > and digging deeper into the product. I am most familiar with the versions > included in CDH - both product and docs. > > One of my first questions is what is the target audience for the docs? and > what are the expectations in skill for the expected contributors? > > Are we looking for install, admin, user docs for security/system > administrators using the product directly? > Are we expecting compliance auditors to be using these docs? > Are we expecting the primary "customer" to be the major Hadoop > distributions repackaging the product and docs? > > A mix of documentation is probably needed. > I think expanding/updating overviews and tutorials in the wiki with help > those evaluating the product (both as admins or for security audits) > I think modular books in a version controlled system is best for full > guides and consumption by the downstream distros. > > I am most familiar with publican (content is docbook XML) in a git repo. > The XML content is not the most inviting for new contributors but the > structure makes it easy to be modular which in turn allows the distros to > integrate content into their own docs - and hopefully contribute back up to > the project any additions, corrections, and changes. Git also allows easy > branching for new major versions so the older content remains available. > Branching can also be used to allow full guides to be translated. I was > most active in the Fedora Docs during their transition from wiki to > publican which also generated better coordination with and contribution > from the downstream Red Hat Docs team as well as translations teams. > > If we are reviewing creation and delivery processes, think big. The > information may be able to fit in a dozen wiki pages right now but how long > until there is a full admin guide? What if it grows enough for multiple > guides? > > There is also the related, but separate project of documenting the project > processes themselves and how to onboard new contributors. This is not only > for product code, but also test suites, test days, and contributions to the > documentation. That content tends to be more static and a wiki works well. > > I'll have more specific content questions in a few weeks. Meanwhile, thanks > for letting me look in on your dev list. > > -Susan > > > > > On Mon, Oct 12, 2015 at 4:38 PM, Sravya Tirukkovalur <[email protected]> > wrote: > > > Hello folks, > > > > I had an opportunity to connect with Susan (cced here), who is interested > > in getting involved with our project and helping us out with the > > documentation. Susan has a lot of expertise in technical training and > docs. > > And she is very involved in the Fedora project. Thanks @David for the > > intro! @Susan, very excited to connect with you! > > > > I and Susan have briefly discussed about the state of documentation and > > what we want to accomplish to make it is easy for both sentry users and > > developers to find information. And I wanted to move the discussion to > the > > dev list so that every body can chime in their ideas and collaborate on > it. > > > > Here are some of my thoughts: > > - Currently we do have some documentation in the wiki and some > information > > on our website. Would be good to take a step back and consolidate this > > information to find the gaps in it. For example, our tutorial on our > > website is pretty old, we should make sure our landing page has relevant > > and latest information. > > - We should work on our java docs and make sure all our public interfaces > > are properly documented. > > - Might also help to have a version controlled doc system. > > > > Regards, > > > > > > -- > Susan Lauber, (CCAH, CCHSB, RHCX, RHCA, RHCSS, RHCVA, CISSP) > Lauber System Solutions, Inc. > http://www.laubersolutions.com > gpg: 15AC F794 A3D9 64D1 D9CE 4C26 EFC3 11C2 BFA1 0974 >
