On Fri, Jun 29, 2012 at 4:20 PM, Jessica Tomechak <[email protected]> wrote: > Hello community, > > Until recently, CloudStack had one writer (me). Two months ago we added > Radhika PC (cc'd). We've both been working to get the documentation into a > state where the community can contribute.
First, thanks for that work- .docx is abysmal for collaboration. > 1. > How should a doc contribution be submitted? Can we use the same patch > submission process as for code, or do we need some modifications? Well currently there are three ways to do this. Email, ReviewBoard, and bug tracker. No reason you couldn't do all three (though there are some slight modifications you'd have to make if you use a separate repo. > > 2. > Who reviews a doc bug fix? Who reviews a large new document? Only a > maintainer? Or does the community at large review all docs? Would it be > useful to set up an alias like cloudstack-doc-reviewers? Any special tweaks > when using the Review Board for doc patches? Technically any committer would be able to commit a docs patch (regardless of repo setup) A maintainer of 'docs' would be someone who stepped up and volunteered to manage the queue of patches. There shouldn't be a cloudstack-doc-reviewers, as that's exclusionary rather than inclusionary, IMO. If you use a separate repo - you will have to have an additional ReviewBoard target setup. > > 3. > What constitutes a doc review? It completely depends on the patch (just as with code). Grammar only changes would be different than vast chunks of new content. > We'd like to have hands-on testing of how-to > docs. OK, so this means that you'll be testing it? > Can this be handled by volunteers from the community? You are the community (or a part of it) - so in some sense you can do whatever you are willing to do. However, I'd urge caution as to how high you make the bar....it's need to be high enough, but no higher. > Subject matter > experts should check for technical accuracy. So I'll agree and disagree here. If you can't figure it out I am sure SMEs are willing to step in, but surely we can write docs without having to be a SME on every bit of content, or consume a SME's time. > What else should the review > consist of? I don't know, I'd start as light as possible and if there are problems, address that by raising the barrier with more complex reviews. >Are we going to have coding conventions for things like > indentation and white space in the XML tags? I think you should....but...if you are, immediately create a test for it so it becomes part of the testing. (and as a reviewer you should check for whatever convention you establish. That said, I'd be careful how heavily you enforce. (e.g. rejecting a patch for a single tab-instead-of-two-spaces might be overkill.) > > 4. > Who can approve a patch or new document? Any committer, or just the doc > maintainers? Any CloudStack committer can commit to any CloudStack repo. Unless we dramatically restructure and have our own subprojects, that will not change, and honestly I don't think we are at a stage to need that. A maintainer has no additional authority over a committer, they are merely volunteering to make sure the patch queue for a given module is timely managed. (e.g. it's a position of responsibilty, not of authority) > > If we can discuss and agree on these topics (and others that will come > up!), we can add a "contributing to documentation" section to our "how to > contribute" web page. Please make that an edit or patch to the Apache project site.
