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

[Adam Williamson]

On Fri, 2009-10-09 at 08:25 +0000, "Jóhann B. Guðmundsson" wrote:
> On 10/09/2009 01:58 AM, Christopher Beland wrote:

> > The "Debugging Thunderbird" section could use some clarification.  I
> > assume that readers should only attempt to get a stack trace if they
> > experience a crash?

> I say users should always follow that procedure and file the gdb.txt
> regardless if he stack traces or not then again this is something that
> the maintainer needs to clarifies as what he wants on the report along
> with how to handle broken extensions...    

The important question is whether they should try and use gdb if
Thunderbird doesn't crash, and the answer is obviously no...I think
Chris just wants a little bit of text to clarify you only go through the
gdb procedure if your bug involves Thunderbird crashing. If the app
isn't crashing, a stack trace isn't going to provide any useful
information.
 
> > The instructions for using gdb on the Thunderbird page are much more
> > complicated than:
> >
> > https://fedoraproject.org/wiki/StackTraces#Obtaining_a_stack_trace_using_just_GDB

> Interesting perception..
> 
> I would rather say that 
> https://fedoraproject.org/wiki/StackTraces#Obtaining_a_stack_trace_using_just_GDB
> is less informitive than the debugging section since it lacks the sample
> output.  The reason I put the sample output is to take out any mental
> uncertainty ( or insecurity ) the low-knowledge reporter could be
> dealing with. This is how you execute the command. This is the output if
> you are doing it right.....

Looking at both, it seems like each has little bits that aren't in the
other, but as Johann says they're essentially very similar except he
includes example output. I definitely see Johann's rationale for having
example output; I have experienced the case numerous times where you
tell someone to perform operation 'X' and give you the output, they make
a mistake that's obvious to you but isn't to them and the output is
garbage, but they don't know that and attach it anyway, and you have to
go around the loop again explaining what they did wrong and how to fix
it. Example output is a great way to fix that problem. It _does_ make
the section read very long, though. Perhaps we could have a compromise
by showing only a small excerpt of the example output for each
operation?

I think it would be good to combine the two candidates into one
canonical 'gdb instructions' bit, and have that on the stacktraces page.
Thought: can we include a section of the stacktraces page directly into
the 'how_to_debug' page template? I don't recall if that's possible, but
I think it may be...or if we can't, we can certainly set up the
instructions as a page fragment and then include it into both the
template and the stacktraces page. That solves the duplication problem
while still having the instructions in-line in the debugging pages, as
Johann wants.

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