httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Lucien Gentis <lucien.gen...@univ-lorraine.fr>
Subject Re: How to patch the docs
Date Mon, 18 Jul 2016 07:18:32 GMT
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 
> <mailto:rbowen@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 <mailto:rbowen@rcbowen.com> - @rbowen
> > http://apachecon.com/ - @apachecon
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org 
> <mailto:docs-unsubscribe@httpd.apache.org>
> > For additional commands, e-mail: docs-help@httpd.apache.org 
> <mailto: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
>

-- 
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


Mime
View raw message