httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rich Bowen <rbo...@rcbowen.com>
Subject How to patch the docs
Date Fri, 15 Jul 2016 19:11:20 GMT
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


Mime
View raw message