How to handle CloudStack documentation patches: please discuss

[Jessica Tomechak <je...@gmail.com>]

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.

Radhika and I have sent notes already describing the tools we are adopting
to make collaboration possible. Aside from the nuts and bolts of the
infrastructure, we also need to set up some processes. This brings up the
following questions:

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?

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?

3.
What constitutes a doc review? We'd like to have hands-on testing of how-to
docs. Can this be handled by volunteers from the community? Subject matter
experts should check for technical accuracy. What else should the review
consist of? Are we going to have coding conventions for things like
indentation and white space in the XML tags?

4.
Who can approve a patch or new document? Any committer, or just the doc
maintainers?

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.

Thanks in advance for your ideas,

Jessica T.
CloudStack Tech Pubs

Re: How to handle CloudStack documentation patches: please discuss

[David Nalley <da...@gnsa.us>]

On Fri, Jun 29, 2012 at 4:20 PM, Jessica Tomechak
<je...@gmail.com> 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.