httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rich Bowen <rbo...@rcbowen.com>
Subject Re: A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD
Date Wed, 04 Apr 2012 13:39:11 GMT
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_noakes@symantec.com
> +1-415-370-5980

--
Rich Bowen
rbowen@rcbowen.com :: @rbowen
rbowen@apache.org







Mime
View raw message