You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by Rich Bowen <rb...@rcbowen.com> on 2016/07/15 19:11:20 UTC
How to patch the docs
I periodically give a presentation on documentation - how to make your
docs not suck, how to work with users to solve their problems, how to
make it easier for people to contribute to the docs.
I often give advice that we are not following in this docs project. Some
of these are historical (I strongly encourage people to avoid formats
like docbook that have a towering barrier to entry) but others are just
laziness and lack of time. For example, implementing the comment system
was something that I recommended, and Humbedooh implemented, but we're
not leveraging to its full potential just because there are *thousands*
of comments, and it takes time to get through them all.
Anyways, I recently tried to contribute a docs patch to another Apache
project, and ended up giving up in frustration, because I couldn't
figure out how to do it, and didn't want to have to join a bunch of
mailing lists just to fix a typo. In the process, I started wondering
how hard it is to submit a patch to the httpd docs. If, say, I found a
typo, what do I do?
(Contrariwise, I was able to submit a patch to the Mesos docs with very
little work, because they not only made it obvious where to do it, but
were also polite and helpful when I did it wrong the first time.)
Something that I recommend in my presentation is simple - tell me in the
doc how to edit/patch the doc. For example, on my work website -
http://rdoproject.org/ - you'll see an "edit on github" banner on every
page. Simple and easy.
For our docs, I'd like to have something on each page of the docs that
indicates how one might patch the docs. This could simply be a link to
http://httpd.apache.org/docs-project/ or it could be a link to the
ticketing system. Patching our docs is, unfortunately, rather more
complicated than just a link to Github, but any barrier that we can
remove would be good.
Any objections to my making a change to that effect to the docs build
template?
--
Rich Bowen - rbowen@rcbowen.com - @rbowen
http://apachecon.com/ - @apachecon
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: How to patch the docs
Posted by Rich Bowen <rb...@rcbowen.com>.
On 07/18/2016 06:08 AM, Mads Toftum wrote:
> On Fri, Jul 15, 2016 at 03:11:20PM -0400, Rich Bowen wrote:
>> I periodically give a presentation on documentation - how to make your
>> docs not suck, how to work with users to solve their problems, how to
>> make it easier for people to contribute to the docs.
>>
> Is this something that can be found online?
The latest version is at
https://github.com/rbowen/presentations/tree/master/betterfm (source)
and http://boxofclue.com/presentations/betterfm/#/ (rendered) and I'll
be giving a new version at LinuxCon next month in Toronoto. I'm in the
process of rewriting based on lots of feedback the last time.
>
>> I often give advice that we are not following in this docs project. Some
>> of these are historical (I strongly encourage people to avoid formats
>> like docbook that have a towering barrier to entry) but others are just
>> laziness and lack of time. For example, implementing the comment system
>> was something that I recommended, and Humbedooh implemented, but we're
>> not leveraging to its full potential just because there are *thousands*
>> of comments, and it takes time to get through them all.
>>
> Yeah, having a comment system and abandoning it is probably worse than
> not having one. Is there a way to clean out "misplaced" comments and
> stuff that's been incorporated in the docs?
>
>> Anyways, I recently tried to contribute a docs patch to another Apache
>> project, and ended up giving up in frustration, because I couldn't
>> figure out how to do it, and didn't want to have to join a bunch of
>> mailing lists just to fix a typo. In the process, I started wondering
>> how hard it is to submit a patch to the httpd docs. If, say, I found a
>> typo, what do I do?
>>
> I don't think we should do anything for other projects, but in our case
> the comment system seems like a pretty darn obvious way. It doesn't
> really get any easier than that.
>
>> (Contrariwise, I was able to submit a patch to the Mesos docs with very
>> little work, because they not only made it obvious where to do it, but
>> were also polite and helpful when I did it wrong the first time.)
>>
> Our page could probably do with a bit of an update, but now that I look
> at it I don't think it's too horrible. There's pretty much all you need
> to know.
>
>> Something that I recommend in my presentation is simple - tell me in the
>> doc how to edit/patch the doc. For example, on my work website -
>> http://rdoproject.org/ - you'll see an "edit on github" banner on every
>> page. Simple and easy.
>>
> A page source link pointing to the relevant file in svn? I suppose you
> could do that.
>
>> For our docs, I'd like to have something on each page of the docs that
>> indicates how one might patch the docs. This could simply be a link to
>> http://httpd.apache.org/docs-project/ or it could be a link to the
>> ticketing system. Patching our docs is, unfortunately, rather more
>> complicated than just a link to Github, but any barrier that we can
>> remove would be good.
>>
> Given the commenting system, I don't know how badly we need to add more
> links. If anything, I'd much rather have it go to
> http://httpd.apache.org/docs-project/ than to bugzilla.
>
>> Any objections to my making a change to that effect to the docs build
>> template?
>>
> See above :)
>
> vh
>
> Mads Toftum
>
--
Rich Bowen - rbowen@rcbowen.com - @rbowen
http://apachecon.com/ - @apachecon
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: How to patch the docs
Posted by Mads Toftum <ma...@toftum.dk>.
On Fri, Jul 15, 2016 at 03:11:20PM -0400, Rich Bowen wrote:
> I periodically give a presentation on documentation - how to make your
> docs not suck, how to work with users to solve their problems, how to
> make it easier for people to contribute to the docs.
>
Is this something that can be found online?
> I often give advice that we are not following in this docs project. Some
> of these are historical (I strongly encourage people to avoid formats
> like docbook that have a towering barrier to entry) but others are just
> laziness and lack of time. For example, implementing the comment system
> was something that I recommended, and Humbedooh implemented, but we're
> not leveraging to its full potential just because there are *thousands*
> of comments, and it takes time to get through them all.
>
Yeah, having a comment system and abandoning it is probably worse than
not having one. Is there a way to clean out "misplaced" comments and
stuff that's been incorporated in the docs?
> Anyways, I recently tried to contribute a docs patch to another Apache
> project, and ended up giving up in frustration, because I couldn't
> figure out how to do it, and didn't want to have to join a bunch of
> mailing lists just to fix a typo. In the process, I started wondering
> how hard it is to submit a patch to the httpd docs. If, say, I found a
> typo, what do I do?
>
I don't think we should do anything for other projects, but in our case
the comment system seems like a pretty darn obvious way. It doesn't
really get any easier than that.
> (Contrariwise, I was able to submit a patch to the Mesos docs with very
> little work, because they not only made it obvious where to do it, but
> were also polite and helpful when I did it wrong the first time.)
>
Our page could probably do with a bit of an update, but now that I look
at it I don't think it's too horrible. There's pretty much all you need
to know.
> Something that I recommend in my presentation is simple - tell me in the
> doc how to edit/patch the doc. For example, on my work website -
> http://rdoproject.org/ - you'll see an "edit on github" banner on every
> page. Simple and easy.
>
A page source link pointing to the relevant file in svn? I suppose you
could do that.
> For our docs, I'd like to have something on each page of the docs that
> indicates how one might patch the docs. This could simply be a link to
> http://httpd.apache.org/docs-project/ or it could be a link to the
> ticketing system. Patching our docs is, unfortunately, rather more
> complicated than just a link to Github, but any barrier that we can
> remove would be good.
>
Given the commenting system, I don't know how badly we need to add more
links. If anything, I'd much rather have it go to
http://httpd.apache.org/docs-project/ than to bugzilla.
> Any objections to my making a change to that effect to the docs build
> template?
>
See above :)
vh
Mads Toftum
--
http://flickr.com/photos/q42/
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: How to patch the docs
Posted by Astrid Malo <ke...@apache.org>.
Am Mon, 18 Jul 2016 09:18:32 +0200
schrieb Lucien Gentis <lu...@univ-lorraine.fr>:
> Hello docs people,
>
> Some remarks :
>
> "Comments" link on each page doesn't indicate clearly enough that its
> purpose is adding comments about the doc itself, instead of being a
> Q&A. I think that's the reason why there are thousands of comments.
> How about replacing it by something like "Report an error, improve
> the doc" ?
+1
>
> Patching the doc : the reader can either add a comment to tell
> there's a typo or another problem with the doc, or add a bug report
> via Bugzilla. What is the best way, knowing that in the latter case,
> the reader has to create an account if he/she doesn't already have
> one, and seeing that, he'll probably go away ?
This might be true fora lot of people. At least for myself. I won't
create an account for minor issues.
kess
> So I think the best way to get problem reports from readers is the
> "Comments" system, provided that its purpose is clearly indicated.
>
> Finally, +1 for rewriting http://httpd.apache.org/docs-project/ page.
>
> Lucien
>
>
>
> Le 16/07/2016 à 07:56, Luis Gil de Bernabé a écrit :
> >
> > El 15 jul. 2016 21:11, "Rich Bowen" <rbowen@rcbowen.com
> > <ma...@rcbowen.com>> escribió:
> > >
> > > I periodically give a presentation on documentation - how to make
> > > your docs not suck, how to work with users to solve their
> > > problems, how to make it easier for people to contribute to the
> > > docs.
> > >
> > > I often give advice that we are not following in this docs
> > > project. Some of these are historical (I strongly encourage
> > > people to avoid formats like docbook that have a towering barrier
> > > to entry) but others are just laziness and lack of time. For
> > > example, implementing the comment system was something that I
> > > recommended, and Humbedooh implemented, but we're not leveraging
> > > to its full potential just because there are *thousands* of
> > > comments, and it takes time to get through them all.
> > >
> > > Anyways, I recently tried to contribute a docs patch to another
> > > Apache project, and ended up giving up in frustration, because I
> > > couldn't figure out how to do it, and didn't want to have to join
> > > a bunch of mailing lists just to fix a typo. In the process, I
> > > started wondering how hard it is to submit a patch to the httpd
> > > docs. If, say, I found a typo, what do I do?
> > >
> > > (Contrariwise, I was able to submit a patch to the Mesos docs
> > > with very little work, because they not only made it obvious
> > > where to do it, but were also polite and helpful when I did it
> > > wrong the first time.)
> > >
> > > Something that I recommend in my presentation is simple - tell me
> > > in the doc how to edit/patch the doc. For example, on my work
> > > website - http://rdoproject.org/ - you'll see an "edit on github"
> > > banner on every page. Simple and easy.
> > >
> > > For our docs, I'd like to have something on each page of the docs
> > > that indicates how one might patch the docs. This could simply be
> > > a link to http://httpd.apache.org/docs-project/ or it could be a
> > > link to the ticketing system. Patching our docs is,
> > > unfortunately, rather more complicated than just a link to
> > > Github, but any barrier that we can remove would be good.
> > >
> > > Any objections to my making a change to that effect to the docs
> > > build template?
> > >
> > > --
> > > Rich Bowen - rbowen@rcbowen.com <ma...@rcbowen.com> -
> > > @rbowen http://apachecon.com/ - @apachecon
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> > <ma...@httpd.apache.org>
> > > For additional commands, e-mail: docs-help@httpd.apache.org
> > <ma...@httpd.apache.org>
> > >
> >
> > Hello Rich,
> > I understand your point i was on tye same situation some months
> > ago, and i was able to edit the webpage were it explains how to
> > contribute, in my opinion i think we need to reedit the main page
> > http://httpd.apache.org/docs-project/ because its a bit
> > confusing(at least it was for me).
> > You can count on me to help you on this.
> > Regards
> >
>
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: How to patch the docs
Posted by Lucien Gentis <lu...@univ-lorraine.fr>.
Hello docs people,
Some remarks :
"Comments" link on each page doesn't indicate clearly enough that its
purpose is adding comments about the doc itself, instead of being a Q&A.
I think that's the reason why there are thousands of comments. How about
replacing it by something like "Report an error, improve the doc" ?
Patching the doc : the reader can either add a comment to tell there's a
typo or another problem with the doc, or add a bug report via Bugzilla.
What is the best way, knowing that in the latter case, the reader has to
create an account if he/she doesn't already have one, and seeing that,
he'll probably go away ?
So I think the best way to get problem reports from readers is the
"Comments" system, provided that its purpose is clearly indicated.
Finally, +1 for rewriting http://httpd.apache.org/docs-project/ page.
Lucien
Le 16/07/2016 � 07:56, Luis Gil de Bernab� a �crit :
>
> El 15 jul. 2016 21:11, "Rich Bowen" <rbowen@rcbowen.com
> <ma...@rcbowen.com>> escribi�:
> >
> > I periodically give a presentation on documentation - how to make your
> > docs not suck, how to work with users to solve their problems, how to
> > make it easier for people to contribute to the docs.
> >
> > I often give advice that we are not following in this docs project. Some
> > of these are historical (I strongly encourage people to avoid formats
> > like docbook that have a towering barrier to entry) but others are just
> > laziness and lack of time. For example, implementing the comment system
> > was something that I recommended, and Humbedooh implemented, but we're
> > not leveraging to its full potential just because there are *thousands*
> > of comments, and it takes time to get through them all.
> >
> > Anyways, I recently tried to contribute a docs patch to another Apache
> > project, and ended up giving up in frustration, because I couldn't
> > figure out how to do it, and didn't want to have to join a bunch of
> > mailing lists just to fix a typo. In the process, I started wondering
> > how hard it is to submit a patch to the httpd docs. If, say, I found a
> > typo, what do I do?
> >
> > (Contrariwise, I was able to submit a patch to the Mesos docs with very
> > little work, because they not only made it obvious where to do it, but
> > were also polite and helpful when I did it wrong the first time.)
> >
> > Something that I recommend in my presentation is simple - tell me in the
> > doc how to edit/patch the doc. For example, on my work website -
> > http://rdoproject.org/ - you'll see an "edit on github" banner on every
> > page. Simple and easy.
> >
> > For our docs, I'd like to have something on each page of the docs that
> > indicates how one might patch the docs. This could simply be a link to
> > http://httpd.apache.org/docs-project/ or it could be a link to the
> > ticketing system. Patching our docs is, unfortunately, rather more
> > complicated than just a link to Github, but any barrier that we can
> > remove would be good.
> >
> > Any objections to my making a change to that effect to the docs build
> > template?
> >
> > --
> > Rich Bowen - rbowen@rcbowen.com <ma...@rcbowen.com> - @rbowen
> > http://apachecon.com/ - @apachecon
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> <ma...@httpd.apache.org>
> > For additional commands, e-mail: docs-help@httpd.apache.org
> <ma...@httpd.apache.org>
> >
>
> Hello Rich,
> I understand your point i was on tye same situation some months ago,
> and i was able to edit the webpage were it explains how to contribute,
> in my opinion i think we need to reedit the main page
> http://httpd.apache.org/docs-project/ because its a bit confusing(at
> least it was for me).
> You can count on me to help you on this.
> Regards
>
--
Lucien GENTIS
UNIVERSITE DE LORRAINE - ESPE
Centre de Ressources Informatiques
5, Rue Paul Richard
C.O. 3 - MAXEVILLE
54528 LAXOU-CEDEX
T�l. 03 72 74 13 28
Email : lucien.gentis@univ-lorraine.fr
Re: How to patch the docs
Posted by Luis Gil de Bernabé <lj...@googlemail.com>.
El 15 jul. 2016 21:11, "Rich Bowen" <rb...@rcbowen.com> escribió:
>
> I periodically give a presentation on documentation - how to make your
> docs not suck, how to work with users to solve their problems, how to
> make it easier for people to contribute to the docs.
>
> I often give advice that we are not following in this docs project. Some
> of these are historical (I strongly encourage people to avoid formats
> like docbook that have a towering barrier to entry) but others are just
> laziness and lack of time. For example, implementing the comment system
> was something that I recommended, and Humbedooh implemented, but we're
> not leveraging to its full potential just because there are *thousands*
> of comments, and it takes time to get through them all.
>
> Anyways, I recently tried to contribute a docs patch to another Apache
> project, and ended up giving up in frustration, because I couldn't
> figure out how to do it, and didn't want to have to join a bunch of
> mailing lists just to fix a typo. In the process, I started wondering
> how hard it is to submit a patch to the httpd docs. If, say, I found a
> typo, what do I do?
>
> (Contrariwise, I was able to submit a patch to the Mesos docs with very
> little work, because they not only made it obvious where to do it, but
> were also polite and helpful when I did it wrong the first time.)
>
> Something that I recommend in my presentation is simple - tell me in the
> doc how to edit/patch the doc. For example, on my work website -
> http://rdoproject.org/ - you'll see an "edit on github" banner on every
> page. Simple and easy.
>
> For our docs, I'd like to have something on each page of the docs that
> indicates how one might patch the docs. This could simply be a link to
> http://httpd.apache.org/docs-project/ or it could be a link to the
> ticketing system. Patching our docs is, unfortunately, rather more
> complicated than just a link to Github, but any barrier that we can
> remove would be good.
>
> Any objections to my making a change to that effect to the docs build
> template?
>
> --
> Rich Bowen - rbowen@rcbowen.com - @rbowen
> http://apachecon.com/ - @apachecon
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
Hello Rich,
I understand your point i was on tye same situation some months ago, and i
was able to edit the webpage were it explains how to contribute, in my
opinion i think we need to reedit the main page
http://httpd.apache.org/docs-project/ because its a bit confusing(at least
it was for me).
You can count on me to help you on this.
Regards