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

[James Laska]

On Thu, 2009-10-08 at 10:29 +0000, "Jóhann B. Guðmundsson" wrote:
> On 10/07/2009 09:01 PM, Adam Williamson wrote: 
> > On Wed, 2009-10-07 at 15:40 -0400, Christopher Beland wrote:
> > 
> > Thanks to Johann for the idea and the template and everyone else for
> > running with the idea!
> > 
> >   
> > > On Wed, 2009-10-07 at 17:18 +0000, "Jóhann B. Guðmundsson" wrote:
> > >     
> > > > > https://fedoraproject.org/wiki/StackTraces 
> > > > >         
> > > > Not targeted at low-knowledge audience 
> > > >       
> > > Well, at least it's a starting point.  It might be best to put material
> > > appropriate to novice users up front on that page (how to use Bug Buddy,
> > > ABRT, etc.), while retaining advanced material farther down.
> > >     
> > Yes, I think Chris' general idea is correct, but Johann is correct that
> > we don't current have sufficiently good centralized info on standard
> > gdb / strace use. I think the best approach would be to add the
> > necessary stuff to the StackTraces page and then link to that from each
> > 'how to debug' page, as Chris suggests. Johann, do you think you could
> > do a draft of this, or could you, Chris?
> > 
> >   
> 
> We can create a gdb template with a link to
> https://fedoraproject.org/wiki/StackTraces encase end users wants to
> learn more on how to use gdb That template could contain the
> instructions of what I wrote I on the Thunderbird page so the novice
> enduser can produce gdb.txt file to attache to the report without the
> need to learn the whole internet before doing so. 
> 
> > > > > It might be a good idea to put a link at the top of each "How to" page
> > > > > back to this page, saying, "If you need to file a bug, here's general
> > > > > information on how to do that.  I've added suggested language to the
> > > > > template page.
> > > > >         
> > > > I think that info should reside under <component>#Reporting_Problems not
> > > > on the "How to debug component" page.
> > > >       
> > > A lot of components don't have homepages for which there is a Reporting
> > > Problems section.  I'm not sure every component needs its own
> > > homepage...
> > > 
> > > Perhaps you have a different scope in mind than what I am thinking?  So
> > > far, we have both "Bug_info_<component>" and "How_to_debug_<component>"
> > > pages.  I was assuming these were essentially the same thing by
> > > different names.  
> > >     
> > Yes, they are, AFAIK (Bug_info_<component> was the naming scheme I came
> > up with, How_to_debug_<component> was someone else's, but we were
> > designing the same kind of page).
> > 
> >   
> 
> Does not actually matter what we call these pages as long as they have
> consistent naming and consistent layout.  
> 
> 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.  
  
We don't need to build the perfect system from the start.  Trying to
would just end up with everyone being unhappy with the result.  Perhaps
focusing on some incremental wins.  

We are  beginning to build out some quality guides to assist testers so
that they can resolve their own problems.   Adam is right, the more
content we have, the more it will suffer from rot.  So instead of
mandating that every component needs to have a series of corresponding
wiki templates, let's try something else.  I've had many problems with X
and a few with dracut in recent months.  Those 2 wiki pages are great.
But I wouldn't be served at all by a comprehensive page on how to debug
'at'.  That's not that 'at' isn't important, but it shouldn't be part of
our primary focus when we are trying to add value.  Besides, what is
established+proposed here would allow for anyone to provide content for
their favorite apps using the previously suggested wiki template, cool!

Going back to what pages do we focus on.  Seems like the informal
approach that's happening now is ideal.  Build pages for high-impact
features that will introduce a high bug rate (e.g. xorg-x11-drv-* and
dracut).  This can be part of the service offered by the QA group as
features come online.  We can provide focused test days and some
documentation to aid others to self-diagnose and/or provide quality bug
reports.

Thanks,
James
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-test-list/attachments/20091008/81e460d9/attachment.sig>