httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Astrid Malo <k...@apache.org>
Subject Re: How to patch the docs
Date Mon, 18 Jul 2016 08:26:17 GMT
Am Mon, 18 Jul 2016 09:18:32 +0200
schrieb Lucien Gentis <lucien.gentis@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 
> > <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
> >  
> 


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Mime
View raw message