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 - @rbowen http://apachecon.com/ - @apachecon --------------------------------------------------------------------- To unsubscribe, e-mail: docs-unsubscr...@httpd.apache.org For additional commands, e-mail: docs-h...@httpd.apache.org
