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
