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