Standardize/ have consistency in the layout of How_to_Debug_<component> wiki pages.

[Adam Williamson]

On Thu, 2009-10-08 at 10:29 +0000, "Jóhann B. Guðmundsson" wrote:
> One thing people need to ask themselves is.. Do we want to be able to
> point reporters to a reporting page for a given component which will
> contain all the information he needs to file a good report against the
> component or do we want him to follow million links and read through
> tons of man pages how to's upstream documents and more while being
> redirect through the whole internet and all of this just to file a
> single report..  
> 
> I suggest that we have a single how to debug page for each component
> which we can point the reporter to like "Hey here's the page on how to
> report against the component you encountered a bug with. It contains
> all the necessary information on what you need to file good report
> against this component ( yes including the minimal gdb info as I wrote
> on the thunderbird page ) and a couple of links encase you want to
> learn more and avoid as much as possible redirecting them between
> pages in the wiki or somewhere else on the intertubes for that
> matter..  
> 
> Asking users to follow link "A" to get to page "C" which will contain
> info on component "E"  always remind me on Twelve Tasks of Asterix
> (Les Douze travaux d'Astérix ) an animated feature film from 1976
> where one of Asterix and Obelix tasks was to find permit A38 in the
> place that sends you mad! which was a mind-numbing multi-storey
> building founded on bureaucracy and staffed by clinically unhelpful
> people who direct all their clients to other similarly unhelpful
> people elsewhere in the building.  
> 
> Reporters I ask you this..
> 
> Do you want to run around in the wiki to find the info needed to file
> areport against an component or do you want to have all that info on a
> single page ? 

I think that overstates the issue. I agree that it's a bad idea to make
people run around a long chain of links to different pages, but that's
not the vision here. The vision is to have specific pages for one or two
specific operations linked directly from the debug pages; you'd never
have to go more than two levels deep.

I think that's fine. There's a balance here. The problem with writing
the instructions into each page separately is rot; if you have multiple
instances of any text in a Wiki, it's almost inevitable that they'll
diverge, that one will be correctly updated and the other won't, and
this will lead to problems. For instance, it would be insane to write
instructions on installing packages into every single page which
mentions installing packages; we just have a page about package
management and link to it where appropriate. That way, when something
about package management changes, we don't have to update a couple of
thousand different pages.

There's definitely a balance to be maintained here, but personally I
think the separation approach will work best for this particular case
(instructions on getting useful crash traces).

-- 
Adam Williamson
Fedora QA Community Monkey
IRC: adamw | Fedora Talk: adamwill AT fedoraproject DOT org
http://www.happyassassin.net