On 4.3.2016 15:23, Martin Kosek wrote: > On 03/04/2016 03:11 PM, Petr Spacek wrote: >> Hello, >> >> I've updated Feature template to make sure that important the design >> decisions >> are recorded somewhere. >> >> Of course all this is open for discussion. I did this soon because I believe >> that it is better to actually see how it looks like instead of discussing >> vaporware. Wiki has revert button if necessary, feel free to use it. >> >> New texts: >> http://www.freeipa.org/page/Feature_template#Design_Assumptions > > Looks good to me. > >> http://www.freeipa.org/page/Feature_template#Use_Cases > > Does not look good to me. Practical examples of how features is used is in How > to Test section, ideally organized by Use Cases, like in > http://www.freeipa.org/page/V4/User_Certificates#How_to_Test > > If we start adding gory details and examples right in Use Cases section, we > would kill the clarity of that section that intends to just give you overview > of the use cases.
Okay, now I understand that. Funnily enough the only thing I changed is addition of bullet "* Explicitly list use cases which were considered but will not supported for some reason. Include the reason, too ;-)" The text you are criticizing is there from the very first version of the page [2012-07-24T21:09:49 as can be seen on http://www.freeipa.org/index.php?title=Feature_template&oldid=5161]. > I would rather imagine something like > > http://www.freeipa.org/page/V4/Authentication_Indicators#Strong_Authentication_on_Selected_System > > which is an impromptu format for the new User Story based approach. The > expectations is that rest of the page will then work with these User > Stories/Use Cases, whether it is Design, How To Test, UI examples or Test > Plan. Agreed. >> I also did one unrelated change: >> Now "Feature Management" chapter precedes "Design" chapter with all the gory >> details. This should make the page more useful for random users who find it >> using a search engine. >> >> Intents: >> 1. Consider usability *very* early in the design process. >> 2. Think about LDAP schema support for UI workflows very early. > > These are good intents. However, while I agree with the intents, I am curious > how this is supposed to work, because the CLI/UI often works with the terms > that are being defined in Design. > > See for example here: > http://www.freeipa.org/page/V4/User_Certificates#Feature_Management > It already assumes you know some parts of the design, like matching attribute. > > Or: > http://www.freeipa.org/page/V4/OTP#Feature_Management > It already assumes you know what OTP token is, what Radius Proxy server is and > how it relates, etc. Well, that points to an interesting problem of user interface design. Is the user assumed to read the *design* page before using the feature (so he knows the terms as you pointed out)? If it is true then we failed spectacularly at providing usable user interfaces. Looking at https://www.nngroup.com/articles/ten-usability-heuristics/ second principle: # Match between system and the real world ## The system should speak the users' language, with words, phrases and concepts familiar to the user, rather than system-oriented terms. Follow real-world conventions, making information appear in a natural and logical order. My understanding to this is that terms should be 'the usual' terms used in given field. FreeIPA did not invent neither of OTP, RADIUS, DNS, PKI, AD etc. Interface should be self-describing. If it is not then we failed. If there is hard to understand but standard terminology, link to an external article and do not spend time on describing it 25th time (most likely using slightly inconsistent terms). Obviously there will be exceptions but wiki has hyperlinks so this can be handled if absolutely necessary. >> DNS locations proved that UI is a nightmare which is better to think about in >> the very beginning, even before thinking about LDAP schema. >> >> I hope it will help in long term. > > While it may make sense to *think* about the interfaces first, why does it > also > have to be in the design page as the first thing, given it breaks the natural > and logical flow of the text? In my eyes this is more logical and makes the page more useful to a wider audience as I explained in the previous e-mail. AFAIK 'How to test' section was added purposely to make the page usable by non-developers and this is just going in the same direction. Looking at TOC the developer-only sections are just 'Design' and 'Implementation'. If we wanted to be radical and wanted to make the page really nice, shiny, logical, and easy to use by causal users we could move Design and Implementation into sub-page /all-the-gory-details. I understand that could be too radical. -- Petr^2 Spacek -- Manage your subscription for the Freeipa-devel mailing list: https://www.redhat.com/mailman/listinfo/freeipa-devel Contribute to FreeIPA: http://www.freeipa.org/page/Contribute/Code
