Major criteria re-write / re-design proposal

[Tim Flink]

On Fri, 08 Mar 2013 17:24:38 -0800
Adam Williamson <awilliam at redhat.com> wrote:

<snip>

> 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.

Yeah, I think that not confining ourselves to a sentence or two will
really help here. Trying to fit all of the corner cases and specifics
into a small area leads to the "difficult to understand unless you
already know what it means" and making it more verbose makes
references difficult and leads to a Wall-o-Text.

> '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.

I like the idea of keeping the reasons written down somewhere that's
easy to discover - it helps to explain why some things are blockers and
other things aren't. It should also reduce the need to search through
archives for the "where did that come from and why?" question that we
hit from time to time.

> 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.

Yeah, I agree that the display isn't perfect but I also think that the
hard part is getting all of the information together and rewriting it.
The display of the information is helpful and can aid in making it more
easily understandable but is secondary to the content.

> 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.

Overall, I think it's an improvement over what we had for F18 - not as
much implicit information and much better organization. I'd also rather
not fall back to the F18 criteria style - even if the presentation
isn't perfect, it's still better than where we were.

> 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.

Agreed - when I did the alternative format mockup, it was pretty easy
to translate the wiki page into RST and that could likely be scripted
if we needed to. Changes to wiki markup would likely be easier than it
was to translate the data to Sphinx.

> 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.

My argument for eventually moving the criteria out of the wiki is
mostly that it gives us more flexibility in presentation and format.
From the mockup that Adam mentioned, I think it would be possible but
it's going to be a bit of work - if we do end up doing this, I'd like to
ask the design team for help on how the information would be presented
and we really don't have the time to get that done before F19. The
details are probably outside the scope of this thread and we can
discuss them elsewhere.

> Really interested to hear everyone's feedback on this - thanks, folks!

In summary - I really like the idea overall but I agree that the
display of the information isn't perfect. I'm definitely +1 on moving
forward with this for F19.

Thanks for pulling all of this together,

Tim
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 490 bytes
Desc: not available
URL: <http://lists.fedoraproject.org/pipermail/test/attachments/20130311/a04252b8/attachment.sig>