Mailing List Archive: Apache: Docs

A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD

Index | Next | Previous | View Threaded

Geoffrey_Noakes at symantec

Apr 3, 2012, 4:01 PM

Post #1 of 7 (205 views)
Permalink

A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD

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 [at] symantec<mailto:Geoffrey_noakes [at] symantec>
+1-415-370-5980

Geoffrey_Noakes at symantec

Apr 3, 2012, 4:02 PM

Post #2 of 7 (197 views)
Permalink

A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD [In reply to]

When: Monday, April 23, 2012 1:00 PM-2:00 PM (UTC-08:00) Pacific Time (US & Canada).
Where: To join this Conference Call, call +1-719-867-4947 or +1-877-805-0966, pass code 185-778-7088; PDAs: +1-877-805-0966x1857787088#

Note: The GMT offset above does not reflect daylight saving time adjustments.

*~*~*~*~*~*~*~*~*~*

This schedules a conf call to talk about Symantec’s offer to rewrite the Apache HTTPD-related documentation.

This site lists dial-in numbers for non-US countries: http://pages.pgi-email.com/page.aspx?qs=5c591a8916642e736439bf71e62cedaaba1ddbb5cad1d2d6e01ed63a408087cbebd83a3a2694f21a3b65ad41f9b9a27acb70f58e26f8aea773dc640b5aa7d6e673b52830d513c2b901a6660c8d0b42ba6761d6ba5e4cf645
I invite you to forward this to others that may be joining us.

Agenda:
• No PowerPoints or other presentation materials, we'll just talk this through, no preparation needed
• 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
• Decide if there is merit in working together (or not), and decide on next steps

Thanks...

Geoff

Attachments:

message-rfc822.eml (13.2 KB)

wrowe at rowe-clan

Apr 3, 2012, 5:56 PM

Post #3 of 7 (187 views)
Permalink

Re: A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD [In reply to]

On 4/3/2012 6:01 PM, Geoffrey Noakes wrote:
>
> 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?).

Geoffrey,

thank you for your offer. There is no part of our documentation which couldn't
benefit from closer attention, rewriting and even refactoring followed up by peer
review/acceptance cycle. That is a good idea.

This whole conversation jumps the shark when we begin suggesting "Corp Co will..."
and I'm afraid you will not have a positive response from this specific line of
inquiry. The docs team welcomes documentation authors. The docs team is not
soliciting a writing shop, editing shop or publishing shop.

Corporations are appreciated by the foundation, but not respected. No corp will
ever be a project committer. No corp will ever be credited as an author. The
ASF is entirely about the contributions of specific authors (code, and docs) and
their contributions to the project's ecosystem. This is just one reason why some
incubation efforts at the ASF may fail, a simple culture war.

The way this project works is write a patch. Make it small enough for review.
Post it to docs@ (or dev@ or the issue tracker or the wiki, but turn right back
around and point to it in a note to docs@), respond to criticism, and the more
reviewable it is, the quicker it can be reviewed and potentially accepted. As
a given author becomes trusted, and gains experience in interating with the team,
the faster their patches are accepted. When that individuals patches don't need
editing before commit and are too numerous, that individual inevitably gains the
commit karma of their own.

So you are right, doing a 360% review without acceptance is wildly frustrating
and probably not worth doing without committed reviewers. Ask for specific offers
of review from the team so you know several will review the work. Do this in some
incremental and measurable phases which the team can follow in their own limited
volunteer time commitments.

I think we all respect that your crew seeks to be neutral in offering good SSL
guidance to the community. But the very tone of your note suggested to me some
request for a banner "This documentation donated by Symantec, your trusted source
for SSL cryptographic solutions." Which might just well be fact for some of the
readers, but would not be entertained. The collective work of Apache httpd is
wildly diverse and represents hundreds of employed and volunteer contributors
from hundreds of companies.

The mark of a successful committer is that they have enough pride in their own
contribution that they might continue to maintain and improve it, even after the
company who paid them as they wrote it is no longer their employer. Sorry if
we are all coming at this from different perspectives, but the project has a very
rich history of leaving their employers at the side door when they come in to
collaborate with their 'competitors'. Our competition here are colleagues.

If an author steps forward, they will find reviewers, I've read that commitment
on this list several times in the past month.

Respectfully yours,

Bill

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

rbowen at rcbowen

Apr 4, 2012, 6:39 AM

Post #4 of 7 (187 views)
Permalink

Re: A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD [In reply to]

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 [at] symantec
> +1-415-370-5980

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache

tsnyder at gsscomputer

Apr 4, 2012, 6:51 AM

Post #5 of 7 (190 views)
Permalink

RE: A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD [In reply to]

Hello Rich,

I am not sure how I have been listed in the email strings
regarding Apache and your group. I have no idea how to respectfully remove
myself from future mail threads. Can you help please?

Regards,

Tim T Snyder

GSS Computer Technology

(540) 362-7686

P Please consider the environment before printing this e-mail

_____

From: Rich Bowen [mailto:rbowen [at] rcbowen]
Sent: Wednesday, April 04, 2012 9:39 AM
To: docs [at] httpd
Cc: Richard Bowen; Igor Galic (i.galic [at] brainsware); William Rowe
(wrowe [at] apache); Daniel Gruno (rumble [at] cord); Eric Covener
(covener [at] gmail); Rainer Jung (rainer.jung [at] kippdata); Jeff Barto;
Elizabeth Carlassare; Frank Agurto-Machado; Martin Thurmann
Subject: Re: A proposal from Symantec for cleaning up the SSL-related
documentation for Apache's HTTPD

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 [at] symantec

+1-415-370-5980

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache

Geoffrey_Noakes at symantec

Apr 22, 2012, 3:49 PM

Post #6 of 7 (158 views)
Permalink

RE: A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD [In reply to]

Just a reminder: we have this call tromorrow (Monday) at 1 pm Pacific.

Thanks...

Geoff

-----Original Appointment-----
From: Geoffrey Noakes
Sent: Tuesday, April 03, 2012 4:02 PM
To: Geoffrey Noakes; Richard_Bowen; 'Igor Galic (i.galic [at] brainsware)'; 'William Rowe (wrowe [at] apache)'; 'Daniel Gruno (rumble [at] cord)'; 'Eric Covener (covener [at] gmail)'; 'Rainer Jung (rainer.jung [at] kippdata)'; 'docs [at] httpd'; Jeff_Barto; Elizabeth_Carlassare; Frank_Agurto-Machado; Martin_Thurmann; Kyle Hamilton (kyanha [at] kyanha)
Cc: Brad Nicholes
Subject: A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD
When: Monday, April 23, 2012 1:00 PM-2:00 PM (UTC-08:00) Pacific Time (US & Canada).
Where: To join this Conference Call, call +1-719-867-4947 or +1-877-805-0966, pass code 185-778-7088; PDAs: +1-877-805-0966x1857787088#

This schedules a conf call to talk about Symantec's offer to rewrite the Apache HTTPD-related documentation.

This site lists dial-in numbers for non-US countries: http://pages.pgi-email.com/page.aspx?qs=5c591a8916642e736439bf71e62cedaaba1ddbb5cad1d2d6e01ed63a408087cbebd83a3a2694f21a3b65ad41f9b9a27acb70f58e26f8aea773dc640b5aa7d6e673b52830d513c2b901a6660c8d0b42ba6761d6ba5e4cf645
I invite you to forward this to others that may be joining us.

Agenda:
* No PowerPoints or other presentation materials, we'll just talk this through, no preparation needed
* 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
* Decide if there is merit in working together (or not), and decide on next steps

Thanks...

Geoff

<< Message: A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD >>

i.galic at brainsware

Apr 23, 2012, 1:32 AM

Post #7 of 7 (155 views)
Permalink

Re: A proposal from Symantec for cleaning up the SSL-related documentation for Apache's HTTPD [In reply to]

For those of you outside of the Americas:

http://www.wolframalpha.com/input/?i=1%20pm%20pdt%20in%20CEST

----- Original Message -----
>
> Just a reminder: we have this call tromorrow (Monday) at 1 pm
> Pacific.
>
> Thanks…
>
> Geoff
>
> -----Original Appointment-----
> From: Geoffrey Noakes
> Sent: Tuesday, April 03, 2012 4:02 PM
> To: Geoffrey Noakes; Richard_Bowen; 'Igor Galic
> (i.galic [at] brainsware)'; 'William Rowe (wrowe [at] apache)';
> 'Daniel Gruno (rumble [at] cord)'; 'Eric Covener (covener [at] gmail)';
> 'Rainer Jung (rainer.jung [at] kippdata)'; 'docs [at] httpd';
> Jeff_Barto; Elizabeth_Carlassare; Frank_Agurto-Machado;
> Martin_Thurmann; Kyle Hamilton (kyanha [at] kyanha)
> Cc: Brad Nicholes
> Subject: A proposal from Symantec for cleaning up the SSL-related
> documentation for Apache's HTTPD
> When: Monday, April 23, 2012 1:00 PM-2:00 PM (UTC-08:00) Pacific Time
> (US & Canada).
> Where: To join this Conference Call, call +1-719-867-4947 or
> +1-877-805-0966, pass code 185-778-7088; PDAs:
> +1-877-805-0966x1857787088#
>
>
> This schedules a conf call to talk about Symantec’s offer to rewrite
> the Apache HTTPD-related documentation.
>
> This site lists dial-in numbers for non-US countries:
> http://pages.pgi-email.com/page.aspx?qs=5c591a8916642e736439bf71e62cedaaba1ddbb5cad1d2d6e01ed63a408087cbebd83a3a2694f21a3b65ad41f9b9a27acb70f58e26f8aea773dc640b5aa7d6e673b52830d513c2b901a6660c8d0b42ba6761d6ba5e4cf645
> I invite you to forward this to others that may be joining us.
>
> Agenda:
>
> • No PowerPoints or other presentation materials, we'll just talk
> this through, no preparation needed
> • 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
> • Decide if there is merit in working together (or not), and
> decide on next steps
>
>
> Thanks...
>
> Geoff
>
> << Message: A proposal from Symantec for cleaning up the SSL-related
> documentation for Apache's HTTPD >>
>
>

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads