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
