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 -- test mailing list test@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/test
