Am Mon, 18 Jul 2016 09:18:32 +0200 schrieb Lucien Gentis <lucien.gen...@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" <rbo...@rcbowen.com > > <mailto:rbo...@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 - rbo...@rcbowen.com <mailto:rbo...@rcbowen.com> - > > > @rbowen http://apachecon.com/ - @apachecon > > > > > > --------------------------------------------------------------------- > > > To unsubscribe, e-mail: docs-unsubscr...@httpd.apache.org > > <mailto:docs-unsubscr...@httpd.apache.org> > > > For additional commands, e-mail: docs-h...@httpd.apache.org > > <mailto:docs-h...@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-unsubscr...@httpd.apache.org For additional commands, e-mail: docs-h...@httpd.apache.org
