[Freeipa-devel] Feature template - proposed changes

[Martin Kosek]

On 03/04/2016 03:59 PM, Petr Spacek wrote:
> 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].

Heh, sorry the extra rant then - I will therefore blame Rob instead ;-) In all
seriousness, we should clarify that in this Feature template improvement session.

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

Hmm, that's a good point. I am not completely sold yet as I kind of liked the
original logical flow of the design page. But I think we will see that on the
first non-trivial example of design page.

Maybe you could hane the DNS Location design page updated with your proposed
flow, so that we see if it indeed makes sense? That design page can be surely
considered non-trivial.

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

Right.

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

I may surprise you, but I think this is actually not that bad idea. To me, it
seems that the feature page are more and more read by non-developers, whether
it is people supporting other users, quality engineers, UX designers, etc. We
should be thinking of our users when writing the design page in the first
place, so maybe the proposal would actually make sense - I am curious what
others think.