[Freeipa-devel] Feature template - proposed changes

[Petr Vobornik]

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

+1 to Petr's comment. UIs sections should be readable by users. 
Low-level details can be in implementation section.

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