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:

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:

Looks good to me.


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

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

I would rather imagine something like


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.


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.

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:
It already assumes you know some parts of the design, like matching attribute.

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

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

Manage your subscription for the Freeipa-devel mailing list:
Contribute to FreeIPA: http://www.freeipa.org/page/Contribute/Code

Reply via email to