Wiki suggestions

[Adam Williamson]

On Thu, 2009-02-05 at 18:51 -0500, Christopher Beland wrote:
> As someone who has been filing bugs for a long time but who is new to
> this mailing list, I have some suggestions regarding wiki page
> cleanup.

This is awesome. I'm going to take Johann's replies into account as I
write this, too, BTW - just replying to Chris's original mail so we
don't get lost in layers of quotation.

This is stuff I was kicking around with jlaska yesterday and I was going
to bring it to the list soon, but Chris has beaten me to it :)

To take an overview, here, it seems like we all agree on a few things:

* The Wiki area (and all QA-related content on fedoraproject.org) is a
mess and needs to be cleaned up

* The front page is too long and over-complex and we should have a
short, attractive front page which hits the basic points and links to
other areas to cover other things

* The Wiki needs more content and more organization

Does everyone agree on that? If so, at least we have some points to
start from.

> I see four "main" QA pages floating around:
> 
> http://fedoraproject.org/wiki/QA
> http://fedoraproject.org/wiki/User:Johannbg/Draft/QA
> https://fedoraproject.org/wiki/User:Leam
> http://fedoraproject.org/wiki/SIGs/QA

As Johann said, #1 is the current page, #2 is Johann's draft for a
replacement, #3 is Leam's draft for a replacement, and #4 is the old
one.

#4 should just go die in a hole (we can take any good ideas it has into
the New World Order), and we should replace #1 with some kind of
synthesis of Johann's and Leam's ideas and anything else we can all
contribute.

> First of all, some clarity is needed whether BugZappers and QA are
> "subprojects" or a "SIGs", and [[SIG/QA]] should be merged with [[QA]]
> and its subpages.

This is exactly something I am also not clear on and want to clear up.
It's also not clear exactly how BugZappers and 'QA' relate to each
other. But on this topic - I think we are definitely a subproject not a
SIG, and we need to have clear messaging on that in any public reference
area, so it should definitely be clear from the Wiki content that QA is
a sub-project.

> The User:Leam page is intended as a destination for a link from
> http://fedoraproject.org/wiki/Join.  

I think there's actually a wider problem here that we need to bring up
in a wider context (who / what group is overall responsible for the
Wiki?) - there's a wider problem of organization here. See:

http://fedoraproject.org/en/join-fedora
https://fedoraproject.org/wiki/Main_Page

They both include 'Join Fedora' elements, and differ significantly in
content. Also note that the sub-projects list in the second differs from
the sub-projects list in the sidebar of both (which is part of
fedoraproject.org , not fedoraproject.org/wiki ). 

So that should be cleaned up too, I think, but it's not something we can
just do ourselves. For our part, I think there should be a simple front
page which summarizes what QA does and acts as a navigation hub for the
whole QA Wiki area - just as in Johann's draft. I think Johann's draft
is really great in terms of form and layout, that's exactly how a front
page should be. We can tweak the content a little, since - as Johann
said in his reply - it's clear from your analysis of his page that it
doesn't quite convey what he wanted it to convey :)

The 'Get involved in QA' page should be a separate page which is linked
directly from the front page. It should have a little bit at the top
which links back to the front page. 'Join in with QA' links from other
pages - like the join-fedora page - should link directly to the 'Get
involved in QA' page.

> I think it would be a good idea
> to add a "Tester" role to [[Join]], since "OS Developer" to me means
> someone who can write or edit code, but there is plenty of work to be
> done by people who only do testing.

I absolutely agree with that. Currently none of the roles on
https://fedoraproject.org/wiki/Join at the top really looks like one
that 'QA person' fits into. 'OS Developer' is a very awkward fit for
what we do. We should get that addressed. Actually, I think jlaska was
looking at that, and even got an icon done.

I just bet *someone* will complain that it breaks the neat 2x3
organization of the icons, though. That person should be roundly
ridiculed. :)

>   I guess a new table could be
> added for that role, with specific tasks, but I don't think there's a
> need for an entirely separate page just for new volunteers.  The
> "Testing" link points to [[QA]], and making that the one-stop shop for
> "what's up with this subproject" seems like a good idea to me.

As I said, I think the link to our section from any kind of 'how do I
join?' page should point to a specific 'how to join QA' page. That page
links back to the main QA page for anyone who winds up there but wants
an overview before jumping in.

> To be honest, I prefer the current copy of
> http://fedoraproject.org/wiki/QA to the Johannbg draft.  Splitting up
> activities into "Quality Control", "Quality Assurance" and
> "Development" does not seem helpful, especially since "Quality
> Control" and "Quality Assurance" sound like synonyms to many people,
> and the latter has no content in that draft.  And as far as I can
> tell, "Development" (actually fixing bugs) is outside the scope of the
> QA subproject.  

I like Johann's draft in form. The current page is a big long
unattractive laundry list that isn't any fun to read. I have a rule of
thumb that an important 'hub' page like this should fit into one screen
at 1024x768 resolution, and Johann's draft does this perfectly and
doesn't overwhelm you with text. As you and he both agree, the content
needs some work :)

I agree that Development does not belong on this page. I can see
Johann's intent - to show the link between developers (who make the
bugs) and QA (who identify 'em) - but it just confuses things, because
we don't actually *do* development, we just interface with it. That
relationship can be explained elsewhere, it doesn't need to be on the
front page.

And yes, I think you're right in that the difference between QC and QA
is not something people arriving at this page should be expected to be
comfortable with. I think Johann has a hold on a good principle here. I
think the principle is, the 'QA' subproject does rather a lot of
different things and we need to distinguish between them. But I think we
can find a better way of expressing that.

Personally I see a significant difference between what I'd call sorta
'casual' testing and 'programmatic' testing. What the guys internally
here are mostly working on is really detailed, planned testing of
specific components, using customized tools and procedures and so on.
This is what jlaska and wwoods seem to be heavily involved in, and the
more people we can get involved in that effort, the better. But there's
also a more casual side to what happens in this community - for
instance, people like the several who've written to the list lately who
wonder exactly where they fit if they just run Rawhide and report
problems, or run updates-testing packages to see if they work, etc. I'd
like to sort of codify that difference in some way and put it up front
and say there's these two streams to what we do, and they're both valued
and important and we cater to them both here. What do you guys think of
that?

> This is what [[Package Maintainers]] does.
> [[Development]] is also something of a mess; [[QA]] is listed as a
> subset, along with [[PackageMaintainers]] and (implicitly)
> [[ReleaseEngineering]].  This page should probably just go away.

Absolutely. It seems like it doesn't really fit anywhere in the current
Wiki organization. Anything that links to the 'Development' page
probably really wants to link to Package Maintainers or Release
Engineering or QA directly, I don't think there's really a need for a
summary page covering all those groups. Again that's something we need
to take out to whatever wider group is responsible for the overall Wiki
content, though. Luckily there's very few pages that link directly to
Development:

https://fedoraproject.org/wiki/Special:WhatLinksHere/Development

so it shouldn't be a problem to get rid of it.

> The most important thing for [[QA]] to do is clearly list all of the
> activities of the subproject on one page, so volunteers can find tasks
> of interest, and the content for everything is really easy to find.
> As far as I can tell, this is what people do now or want to be able to
> do:

Right. However, as I say for the third time in this mail now :) (oops),
I think the overall Join page should be separate. This does beg the
question, though, of how we cope with the 'join' information for each
area. Does each area have its own 'join' sub-page, or is it just a
section of the main page for the area? WDYT? Is my organization plan
just a PoS in general? :)

> Documented by [[BugZappers]]:
> * Bug Triage: Examine bugs reported by other people and resolve
>   duplicates, incomplete reports, and other problems to save time for
>   [[PackageMaintainers]].  This is coordinated at the independent
>   [[BugZappers]] subproject, which shares the fedora-test-list mailing
>   list.
> 
> Documented by [[Testing]] and [[BugsAndFeatureRequests]]
> * Post-release testing: Run or install Fedora 9 or 10 and report bugs
>   either as you find them spontaneously or while intentionally testing
>   a particular component.
> * Update pre-release testing: Run newly-built software from the Fedora
>   9 or 10 updates-testing repositories and report problems or approval
>   for general public release in Bodhi.
> * Rawhide testing: Run or install Fedora 11 Rawhide (updated daily)
>   and report bugs as you find them spontaneously or while
>   intentionally testing a particular component.
> 
> Systematic QA:
> * Re-testing on request: Test bugs labelled NeedsRetesting.
> * Systematic manual testing: Use one of the test plans listed at
>   [[QA/TestPlans]] to perform a specific list of tasks and report any
>   bugs found.  Especially important when alpha, beta, and release
>   candidate installers are released.
> * Semi-automated testing: Run QA scripts and file problems in Bugzilla. 
> * Develop automated and semi-automated tools for QA testing - see
>   [[Beaker]], [[Automated QA Testing Project]], etc.

Yup. Absolutely. Focusing on specific tasks we do is really great
because it gives people an immediate idea of what goes on and what they
can get involved in. I'm absolutely in favor of task-based focus for the
main pages of the Wiki area, the ones we envisage will get heavy traffic
and lots of 'newbies' landing on them.

> Events:
> * [[QA/Test Days]]
> 
> Documented in other SIGs: 
> * Font testing
> * Documentation testing
> * etc...
> 
> I'm not sure that "Stream Liasion" as described in the Leam draft is
> distinct from these processes, since there are a variety of reasons to
> engage in testing, and different people will naturally focus on
> different components.

Stream liaison is an interesting idea of Leam's that I'm not sure is
fully explained on his draft. The ham radio thing isn't just a random
example, Leam's idea is really based around that kind of very one-task
focused community. There are actually quite a lot of these among Linux
users - groups who have one very specific interest based around software
that others often have little clue about.

Ham radio is one of those. Others include astronomy, biology and
chemistry tools. There are whole ecosystems of very specialized apps out
there for these purposes which I know I have absolutely no clue how to
use, and probably most people using this list have no clue how to use
either. :) Often you need to be, like, a degree level chemist to know
what the heck to do with them. I've PACKAGED a few of 'em before, but I
know I found myself sending the package off to the one guy I knew who
used it and saying "uh...does it work?"

I think Leam's idea is for us to try and liaise with these little
groups, which is a great idea. I'd envisage the best way of working this
as trying to reach out to them and bring someone on board *from* those
groups *to* QA, rather than the other way around. I think he's
absolutely on the ball in that sometimes those little communities become
kinda islands, totally isolated from the main stream of development and
QA, and it would be great to have a link to them.

> I assume Adam is taking the lead on updating the main QA wiki pages,
> so I haven't implemented these suggestions myself (and I didn't feel
> comfortable doing so unilaterally).

Sorry to sound like a 60s throwback (or, for those who get the
reference, Rimmer in that one episode...), but I'd rather be a
facilitator than a leader. I think Chris's ideas in this post are all
absolutely on the ball, Johann's proposed layout for the main page is
great, and some of the ideas in Leam's draft are really useful too, and
I think we can definitely pull them all together into a decent structure
of a small number of pages that really pin down what we do and how to
get involved with it in a clear and attractive way, and I definitely
want everyone to keep involved while we do that.

Do you guys think we should have an IRC meeting during which we could
actually work up drafts for a new set of main wiki pages - or, to keep
it simple, just the main and joining pages - to submit back to the list?
I'd definitely like me, Chris, Leam and Johann to all be there, and then
it'd be awesome for anyone else who has ideas or wants to be involved to
join in.

Thanks guys!
-- 
adamw