httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rich Bowen <rbo...@rcbowen.com>
Subject Re: How to patch the docs
Date Mon, 18 Jul 2016 16:07:18 GMT


On 07/18/2016 06:08 AM, Mads Toftum wrote:
> On Fri, Jul 15, 2016 at 03:11:20PM -0400, Rich Bowen wrote:
>> 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.
>>
> Is this something that can be found online?

The latest version is at
https://github.com/rbowen/presentations/tree/master/betterfm (source)
and http://boxofclue.com/presentations/betterfm/#/ (rendered) and I'll
be giving a new version at LinuxCon next month in Toronoto. I'm in the
process of rewriting based on lots of feedback the last time.



> 
>> 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.
>>
> Yeah, having a comment system and abandoning it is probably worse than
> not having one. Is there a way to clean out "misplaced" comments and
> stuff that's been incorporated in the docs?
> 
>> 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?
>>
> I don't think we should do anything for other projects, but in our case
> the comment system seems like a pretty darn obvious way. It doesn't
> really get any easier than that.
> 
>> (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.)
>>
> Our page could probably do with a bit of an update, but now that I look
> at it I don't think it's too horrible. There's pretty much all you need
> to know.
> 
>> 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.
>>
> A page source link pointing to the relevant file in svn? I suppose you
> could do that.
> 
>> 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.
>>
> Given the commenting system, I don't know how badly we need to add more
> links. If anything, I'd much rather have it go to
> http://httpd.apache.org/docs-project/ than to bugzilla.
> 
>> Any objections to my making a change to that effect to the docs build
>> template?
>>
> See above :)
> 
> vh
> 
> Mads Toftum
> 


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