2016-04-22 8:19 GMT+02:00 Luca Toscano <toscano.l...@gmail.com>: > +docs@ > > 2016-04-20 23:25 GMT+02:00 Marion & Christophe JAILLET < > christophe.jail...@wanadoo.fr>: > >> Le 20/04/2016 19:37, Luca Toscano a écrit : >> >> >> >> 2016-04-18 21:46 GMT+02:00 Luca Toscano <toscano.l...@gmail.com>: >> >>> >>> >>> 2016-04-12 11:38 GMT+02:00 Luca Toscano < <toscano.l...@gmail.com> >>> toscano.l...@gmail.com>: >>> >>>> Hi docs@! >>>> >>>> I have been thinking a way to inform users about our best practices >>>> when finding inconsistencies in the docs, namely checking CHANGES and >>>> Bugzilla first. Most of the times occasional users (or even experienced >>>> ones) tend to forget where the changelog is, if httpd uses bugzilla or not, >>>> etc.. so it would be great in my opinion to add a "reminder" in our manual >>>> pages. The attached patch will add a little section in the right column >>>> (right below "See also") to provide the aforementioned links. >>>> >>>> Position, wording, etc.. can be changed of course, this email is only >>>> meant to discuss the idea. If you don't like it, just state it out loud and >>>> I'll drop it :) >>>> >>>> Let me know your thoughts! >>>> >>>> Luca >>>> >>>> >>> Restarted from the first email to avoid a quoting mess. I attached the >>> final patch that would basically add the "Bugfix checklist" section before >>> "see also" on each module's page. I wanted to restrict the scope of this >>> patch to the places in which occasional users will benefit more rather than >>> adding it to the whole documentation. >>> >>> Christophe, André, Rich: if you want to review the patch it would be >>> really great. If anybody feels very strong against it I'll drop it. >>> >> >> Committed in trunk, you can see some examples in: >> >> https://httpd.apache.org/docs/trunk/mod/event.html >> https://httpd.apache.org/docs/trunk/mod/mod_lua.html >> >> Some comments made so far: >> >> - add the module's name to the bugzilla link (Open bugs) to visualize >> only relevant bugs >> >> +1 >> Having a link that shows 1567 bugs, some opened in 2004 is just bad, IMHO. >> But having, from the doc, a link to only corresponding items would be, >> still IMHO, great. >> > > I agree, the list of 1567 bugs is bad but at least it was a starting point > to let the user know about bugzilla and what to set in the search bar to > find the httpd bugs (I know straightforward but still..). Thanks to Jacob > Champion I have a working version that produces links for modules only > (using {name} in the xsl), but I need to resolve a couple of issues: > > 1) doc pages like "event" are tagged as "mpm_event" in bugzilla, but the > {name} is event. So I'll need to check corner cases and evaluate some > workaround to make everything works correctly. Don't expect to be a lot of > work. > > 2) make sure that all the modules have a related component in bugzilla. > > >> - move Httpd to HTTPD >> >> Having it consistent in the doc would indeed be nice. (we currently have >> many ways to give the name of our web server) >> > > Definitely, I thought that Httpd was fine but HTTPD sounds better. > > >> >> >> - think about moving "Bugfix checkilist" to "Developer Resources" (still >> thinking about this one because I'd like to keep something that connect the >> user looking for a bug to these links). >> >> Or maybe just remove the tittle and move it just before "Comment"? >> > > Could be an option, I wanted to display something that connects the > thought of "ah httpd has a bug!" with "ah I need to check this link > probably" while browsing a doc page. We'll see, the final version is far > from complete! > > >> Maybe, use httpd.docs entity instead of hard coded 2.4 (or equivalent) >> and maybe even have a special case for trunk (link not displayed? Link to >> 2.4 CHANGES?) >> >> Linking to http://httpd.apache.org/dev/dist/ may be bad. Are we sure >> that this folder always have a CHANGES_2.4 file? What about trunk doc? (or >> even 2.2 ?) >> Maybe http://www.apache.org/dist/httpd/CHANGED_2.<version> would be >> better (this is the one used on the main httpd.a.o page) >> > > You are completely right, I will study a better solution. The initial > thought was to avoid applying the change to 2.2 concentrating on 2.4, this > is why I have hardcoded. > > >> >> Maybe "Known issues" would be better that "open(ed) bugs" ? >> > > +1 > > >> >> While at it, maybe add a link to report a bug fir this module ? >> > > +1 great idea! > > Thanks a lot for the great feedback! Really appreciated! I'll start > working on your suggestion as soon as possible and report back to this > thread once I'll have an update :) > > New version just committed, examples:
https://httpd.apache.org/docs/trunk/mod/mod_lua.html https://httpd.apache.org/docs/trunk/mod/event.html Luca
