Geoffrey, Thanks once again for your generous offer. As the author of every one of those comments you quote below, I feel that I should probably respond. All the ignorance expressed in those quotes is *mine*. However, the desire for better docs is pretty universal on this list.
I would be glad to speak with you on the phone, but I can also tell you now what I will tell you on the phone. Apache httpd (and the ASF in general) is a do-ocracy, as one of our directors once said. So, yes, please, we would love to see your documentation contributions, and would gladly incorporate them into the docs. But the way to get that done is to just do it. You have thus far sent us a couple of docs that were really good stuff, but were either not httpd-related, or were at a technical level above my ability to review and do the work of incorporating. Here's what I'd like to see happen, personally. * A review of the existing SSL sub-tree (http://httpd.apache.org/docs/trunk/ssl/) for both content and structure, and a recommendation of how it could be better structures (ie, a T.O.C. for that subtree) * Prose for the various "chapters" in that section. I would be delighted to assist with the process of getting those chapters into correct XML format, although I expect that the examples of what's already there would be a pretty good introduction to how to do that. But, since I'm almost entirely ignorant of anything past the basics of creating certificates and configuring httpd to use them, I can't actually rework *content*. Other folks on the docs team would need to speak for themselves. Each of the people you have CC'ed on this mailing got started on the documentation by just doing it. I found something lacking in the docs and sent changed prose for that section and someone committed it. Eventually I was given commit rights to make those changes myself. William and Eric, at different times, stepped up to be the project management committee chair, by just doing it. Igor and Daniel, like myself, found parts of the documentation lacking, and they stepped up to change them. So my response to your offer is, and has been each time you've made it, a resounding "Yes, please!" But I remain a little confused as to what you envision coming out of a phone call. There is no you and us. There's just us. We want you to be part of us. Please come join the party. Awesome. Now that you're one of us, there's no "us" to reject or accept "your" contribution. There's just us. Welcome to the documentation team. Meanwhile, I've accepted your meeting invitation, and would be glad to speak to you at that time, or sooner (I sent you my personal phone number a week or two ago) if you prefer. I want to enable you to become part of the team, rather than a third party sending us changes. But to rephrase what William said, it would be the individuals on your team who would be part of the docs team, not Symantec. On Apr 3, 2012, at 7:01 PM, Geoffrey Noakes wrote: > I am sending this to those on the Apache documentation list who have replied > to emails related to SSL documentation (I am also copying the list to catch > others that may be interested in this offer from Symantec/VeriSign). Here > are a few comments I’ve seen about the existing Apache HTTPD documentation: > · “Most of ssl/ssl_faq.xml is rubbish” > · “both the FAQ and the howto docs could stand to be completely > scrapped. Unfortunately, SSL is one of the topics about which we seem to know > the least.” > · “If the current arrangement of that doc or set of docs doesn't make > sense, let's scrap it and start over. Most of that prose is a decade old, and > was written by someone who, while a genius in the field, didn't have English > as his first language.” > · “I'm a bit of a stickler for deciding what the scope of our > documentation is, and then not straying too far outside of that. The scope of > our docs is the Apache HTTP Server and how to configure it. While the theory > of SSL itself intersects with configuring mod_ssl, they are separate topics.” > · “I think that the biggest problem in the past with the > contributions has been twofold - one, the format made it difficult to > integrate into the docs. (Translation: I'm basically lazy.) Two, many of us > who are most active on the documentation are completely ignorant of SSL, and > so feel unqualified to review any SSL content.” > > Symantec (previously VeriSign/Thawte/GeoTrust) is willing to take on – for > free – the rewriting of the SSL-related content for Apache HTTPD, but it is > important to us that this work ends up being useful and valuable to the > Apache community, and is not just a make-work project. We will do this in a > CA-independent manner – we do not seek any advantage here, we just want to > make it easier for Apache HTTPD users to understand what they need to know > when implementing SSL (and 100% of them will do so, at some point). We > expect to leverage our skills around writing/publishing meaningful content, > along with the rich set of experiences we have from working with so many > Apache HTTPD users as customers (e.g., what problems end up in our Customer > Support that could be easily be fixed with some Apache documentation?). > > To that end, I will followup this email with a meeting request for Monday, > April 23, at 1:00-1:30 pm Pacific. This will be a short conf call with any > of those in Apache that have an interest in the SSL topic. The main goals > for that call are: > · Understand the scope of the project > · Understand who from the Apache community we should work with > · Understand Apache’s timeframe for getting the rewritten > documentation done > > Thanks… > > Geoff > Geoffrey W. Noakes > Director, Business Development > Symantec Corporation > geoffrey_noa...@symantec.com > +1-415-370-5980 -- Rich Bowen rbo...@rcbowen.com :: @rbowen rbo...@apache.org
