db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jean T. Anderson" <...@bristowhill.com>
Subject Re: New contributors?
Date Fri, 08 Sep 2006 15:15:57 GMT
Jean T. Anderson wrote:
> Daniel John Debrunner wrote:
>>Jean T. Anderson wrote:
>>>Daniel John Debrunner wrote:
>>>>Jean T. Anderson wrote:
...
> In other words, as a reviewer state how much you care that a particular
> item be fixed.
> 
>>>To take a concrete example .....
>>>
>>>I won't commit a doc patch unless:
>>>
>>>- Somebody indicates the changes are technically ok.
>>>- The DITA doc build succeeds.
>>
>>But my (or someone else's) confidence level *might* be lower, if the doc
>>builds then it's ok, better to get more eyes on it earlier, thus I
>>commit it, even if you don't have confidence.
>  
> That's fine -- I view it as an individual committer definition. *I*
> (Jean) won't commit a doc patch unless ... [insert the bullets from the
> above].  I don't expect others to adopt my criteria.
> 
> That much said, I'll be kind of annoyed if somebody does a commit and
> the doc build fails.  :-) And only because I know how time consuming it
> is to chase down doc build problems.

in reference to my saying "I'll be kind of annoyed if somebody does a
commit and the doc build fails" somebody pointed out to me off list that
it is "the kind of comment that can discourage contributors".

Sorry, that wasn't my intention. :-) As the one who recently committed a
patch that broke the build, I can honestly say that, yes, I was annoyed
at myself. But I didn't yell at myself on list, I didn't fall on my
sword. I resolved the problem -- and developed an excellent appreciation
for how difficult it can be to chase down doc build problems... hence my
own personal rule that I won't commit a patch unless the DITA doc build
succeeds.

So, I believe I can help contributors by setting a base level
expectation that the doc build needs to succeed. Furthermore, if the
patch addresses a technical area with which I'm not familiar, I feel the
most confident when somebody with expertise in that area reviews it. I
think my stating my own game plan will encourage contributors and
hopefully reduce that contributor's sense of jumping through hoops.

I could take that further and add some words of encouragement, which are
that you don't necessarily need to know DITA to edit the documentation.

Some contributors *do* know DITA, including Andrew, Laura, Halley, Kim,
and Stan (if I missed your name -- sorry!), and their contributions are
greatly appreciated.

But I'll say straight up that I don't know DITA. I do know html and xml,
so I can modify existing text in the DITA source and troubleshoot
problems with tags that aren't closed. However, I would be kind of lost
if I wanted to add a new topic -- and I'd ask for help getting started.

I don't know how much DITA Mayuresh, Myrna, and Bryan know, but their
cleanups to the Reference Guide and Working With Derby (DERBY-1072,
DERBY-1821, DERBY-1765) are vast improvements that move the
documentation forward for everyone.

I don't know how much DITA Kristian Waagan knows, but his offering to
take a stab at the documentation for DERBY-1659 is fabulous and I
applaud his approach: "If someone wants to add to the content after the
first patch is submitted, feel free to assign yourself to the issue and
bring it forward."

In short, thanks to everyone for improving the docs -- it is sincerely
appreciated! And if I missed thanking you by name in this post, please
let me know.

 -jean

Mime
View raw message