Major criteria re-write / re-design proposal

Sat Mar 9 01:24:38 UTC 2013

Hi, folks. So I've been working on this for a while, but we're getting
close to F19 Alpha time and I really want to get it out there for
comments.

Several people have noted that the release criteria have grown quite a
lot over time. Just compare F13 and F18:

https://fedoraproject.org/wiki/Fedora_13_Alpha_Release_Criteria
https://fedoraproject.org/wiki/Fedora_18_Alpha_Release_Criteria

Individually, all the changes have been good ones that made sense, but
the sum effect of them is that the criteria have turned into a bit of a
Wall-O-Text. It's also true that we've kind of slipped in quite a few
things that 'make sense if you already know what they mean' - some of
the legalistic wording can be a bit confusing if you don't know the
history of what it's doing there.

So I've been trying to come up with some major changes to the criteria
for F19, incorporating all the ideas that have come up in meetings,
retrospective etc. I see there being, broadly, three strands to this:

1) Some major revisions to the wording of the actual criteria themselves
2) Addition of 'metadata' on some criteria
3) Change in the layout/presentation/design of the criteria pages

So bearing in mind that this is something that combines *all three of
the above*, here's what I have so far. I have only done the Alpha page
for now:

https://fedoraproject.org/wiki/User:Adamwill/Draft_alpha_criteria_sandbox

Basically, what I've done is:

DESIGN STUFF
------------

* group the criteria into a few sections, and made (almost) each
individual criterion a sub-section - this might seem a bit odd at first,
but it breaks up the 'wall of text' flow, makes the table of contents
more useful, and gives us stable 'anchors' to link and refer to specific
criteria. Previously they were one big numbered list, but we kept
changing the numbers. In just a couple of places I put two or three
criteria together in a sub-category, where it seemed to make sense (e.g.
'Expected installed system boot behaviour', which is a group of very
closely inter-related criteria).

* Split off the more laborious legalistic bits of various criteria into
separate paragraphs hidden behind 'hide/show' bars. This lets us make
the basic, always-visible criterion text short, simple and clear, and
keep the legalistic exception stuff at a lower level; it should make the
basic intent of the criteria easier to read, reduce the wall-o-text
effect, and make it easier for non-experts to see what criteria apply to
issues.

'METADATA'
----------

* Overlaps with the second point above - the 'clarification' paragraphs
are part of what I'm talking about as metadata. Some of these I just
separated out from existing wording; some I added, as the new design
lets us add quite a lot of 'metadata' without making the basic flow of
the page too long and messy. The 'Supported images must boot' section is
a good idea. We can also write the 'metadata' is a less tortured way
since we're not trying to keep it short; I tried to go with a sort of
relaxed, chatty, conversational style.

* I also added References for a lot of the criteria: for now I've tried
to find the list discussions where criteria were added and/or modified,
and called out a couple of significant discussion threads and bugs. We
could, of course, add far more of these. I think it'll be pretty helpful
for the case where you're looking at a criterion and thinking 'why do we
have that?' - the References section will point you right at the answer.
It does stretch things out design-wise, though.

REWORDING
---------

* As noted above, a lot of the rewording was simply to break off the
legalistic stuff into separate, hidden paragraphs and rewrite the basic
criteria to be clear and simple.

* I also did some major tweaking of a few criteria, though. Most
notably, the 'Initialization requirements' section and the 'Expected
installed system boot behaviour' sub-section. Taking a step back at
looking at what we had in those areas in the current criteria, they
seemed messy and jumbled and hard to understand. I think the new wording
is a lot clearer and simpler in each case, but feedback welcome!

I am generally pretty happy with the *content*, for Alpha, as it stands
now. I really think it's better and clearer now. Splitting the criteria
into a 'basic' text with separate 'metadata' sections really works, I
think, and I'm pretty happy with the specific wording changes I did. I
think the 'References' sections are a useful addition.

I don't think I've completely nailed the *design*, though, so it's
important to remember these two things are separable, to a degree. I
really like the 'basic criteria' / 'metadata' / 'references' concept,
though I'm willing to be argued out of it if people disagree, but we
could represent that in lots of different ways, and this is just one of
them. We could maybe make the references a sort of 'appendix' to the
page, down at the bottom, and have little [ref] links to them in the
sub-section titles, for instance. We could use some other mechanism to
present the metadata sections - or we could keep the 'hide/show' bars,
but change their appearance (this is possible). We could come up with a
completely different way to organize the criteria and metadata sections.
Again, I don't think what I have right now is the best we could come up
with, and it would be awesome if someone could experiment with the
content and come up with some neater ways to represent it.

I'd really like it if we could implement these changes for F19 - we have
all of next week to try and refine them and come up with better design
ideas. If we can't, though, I'll try and at least adapt at least some of
the re-wordings into the existing F18 layout, and we can try again for
F20.

For now I'll work on Beta and Final pages in the same style; if we come
up with a better design, it shouldn't be much work at all to adapt all
the content into it. Doing the actual re-wording and metadata writing
and References: research is a bit of a hard slog, though, so I'll be
getting on with that at the same time as we refine the idea based on
this rough Alpha draft.

It's worth noting that Tim thinks the best way to do this in the long
term would be to move it out of mediawiki and represent it basically as
markdown; he came up with a rough proof of concept for that which looked
pretty nice. But he definitely won't have time to implement that for
F19. Given the timeframe, we're pretty much going to have to stick with
mediawiki for F19. But the good news is, again, the content work is the
really time consuming stuff; we won't be wasting effort if we re-design
in MW for F19 then move it out to a static content generator thing for
F20, as the work in re-writing the criteria texts and adding the
'metadata' texts and the references will always be useful. It's easy to
slot that content into different designs later.

Really interested to hear everyone's feedback on this - thanks, folks!
-- 
Adam Williamson
Fedora QA Community Monkey
IRC: adamw | Twitter: AdamW_Fedora | identi.ca: adamwfedora
http://www.happyassassin.net