[Freeipa-devel] FreeIPA.org/Documentation improvements: request for comments

Tue Oct 22 14:59:15 UTC 2013

On 10/22/2013 04:42 PM, Petr Spacek wrote:
> Hello list,
> 
> here is never-ending discussion about freeipa.org wiki and documentation. Any
> opinions are more than welcome! (Each participating user will receive
> e-thank-you e-mail, I promise! :-D)
> 
> We started the discussion privately and then realized that we should move it to
> mailing list, so some ideas are on the table. This doesn't mean that we have to
> stick with any of current proposals! Bring you ideas!
> 
> On 22.10.2013 15:00, Simo Sorce wrote:
>> On Tue, 2013-10-22 at 13:29 +0200, Martin Kosek wrote:
>>> On 10/21/2013 06:14 PM, Petr Spacek wrote:
>>>> On 21.10.2013 16:24, Martin Kosek wrote:
>>>>> On 10/21/2013 03:54 PM, Dmitri Pal wrote:
>>>>>> On 10/21/2013 04:28 AM, Petr Spacek wrote:
> [snip]
>>>>>>> http://www.freeipa.org/page/Documentation needs significant
>>>>>>> improvement, I agree.
> [snip]
>>>>>
>>>>> Sure. Though I am already tracking this page. Since summer, I have been
>>>>> continuously working on merging the documentation on FreeIPA (like some
>>>>> obscure
>>>>> Tips or three different FAQ sections), obsoleting information that is
>>>>> obsolete
>>>>> and adding warnings or moving v1/v2 development-specific documentation to
>>>>> specific name spaces to avoid them interfering with standard doc and other
>>>>> changes.
>>>>>
>>>>> I think the Documentation page is easier to digest already, compared to what
>>>>> was there before:
>>>>>
>>>>> http://www.freeipa.org/index.php?title=Documentation&diff=6912&oldid=6203
>>>>>
>>>>> So instead of "FreeIPA.org wiki is wrong, awful and eats little puppies" I
>>>>> would prefer to see some concrete ideas for improvements or better UX so
>>>>> that I
>>>>> can follow up on them and continue driving it to be better.
>>>>
>>>> Sure :-) Here are my proposals:
>>>
>>> Thank you!
>>>
>>>> - move "Developer Documentation" away from "/Documentation" to separate page
>>>
>>> Why? It will make it less visible. I think that it contain a lot of useful
>>> information, even for users/power-users.
>>
>> I agree this will plunge us back to the old wiki which was bad.
> 
> I don't belive that regular users search/read design docs. Is the design
> valueable for normal user?

I think so, at least the use cases and work flows can be interesting for users
and administrators. It is just another source of on-topic information at the
minimum

Then
> a) relevant information should be extracted to a article for users
> AND/OR
> b) the design page should be linked directly from Components/FAQ/how-to

I would stick with b). I see a big value in the by component documentation. I
think that the general component overview is a good place for people to learn
what it is, what it does, where to get more information - links to other useful
resources on our wiki - like the aforementioned designs.

Look for example on the Trusts component, some progress already sparkled there:
http://www.freeipa.org/page/TrustsServices

... and should be improved in the future. When we have these components with
information, we can then pretty effectively link to them when writing about
a design (i.e. [[Trusts]] or [[Web UI]]) and thus achieve the right wiki
spirit and interlinked information on FreeIPA.org.

> 
>>>> - move section "By Component" to the end of the page - it is mostly empty ...
>>>> (of course, we can move it back to the beginning after some time!)
>>>
>>> Can be done, though it would be even better to simply add the component
>>> documentation - otherwise we are just hiding a missing doc, not fixing it.
>>
>> Indeed, my aim in creating the section was to highlight what people
>> would like to see and entice some of us in producing more content. It is
>> time we do. If we do it right we'll have great value for our users.
>>
>> And right is not hard, perhaps a bit tedious, but it is just about
>> describing with medium level details the various components with
>> particular care in describing how they interact with others (9bonus
>> point if links between the various pages are provided when we mention
>> interactions.
>>
>> Seem a good project for a new engineer that needs to go through and
>> understand what is going on. By writing these pages he'll have to ask
>> the right questions to older engineers and put them into words, I found
>> it is an invaluable way to actually get to understand the big picture.
> 
> My point is that the wiki should expose useful information *at the beginning*.
> 
> I definitelly agree that filling the wiki with information is much better than
> hidding empty pages, but this great idea doesn't help to users looking for help
> right now.
> 
> I propose to move "Components" to the end (or before "Devel" docs) for now -
> simply to make more valuable sections more visible.
> 
> My intention is to make the /Documentation page more useful right now and I
> belive that this trivial re-ordering will help with that.
> 
> Sure, we can move "Components" back as soon as it will contain some useful
> information.
> 
> Does it explain my intention?

It does, though I still do not think this step is needed. Some components
already have some information (Trusts, Web UI, Client, DNS), which is should
help a bit.

Would adding
http://en.wikipedia.org/wiki/Template:Stub
like warning to the pages make it less confusing and invite people more to help
us improve it? :)

> ...
> Really good work! I wasn't there last week.
> 
> I still think that structure like '3rd party/Zimbra/Authentication' and '3rd
> party/Zimbra/Address Book from LDAP' could be clearer and easier to navigate.
> (Mediawiki can generate even some fancy category/article trees like this one:
> http://en.wikipedia.org/w/index.php?title=Special%3ACategoryTree&target=Computer+science&mode=all
> .)

Makes sense. It would need to be used by every contributor though in order for
the result to make sense.

> 
> Maybe that some non-application-specific articles from 'Working with FreeIPA'
> and 'Interoperability with other systems' sections can be moved to "Components"
> in /Documentation ... (e.g. working with 3rd party certificates, migration, NIS
> etc.)
> 
> 
> What about task-oriented structure for /Documentation ? (Note that one article
> can be linked multiple times.)
> 
> Something like:
> 1. What FreeIPA is - marketing stuff
> 2. Getting Started - articles about installation & client setup
> 3. Cool features (detailed presentations, articles), like:
>  - SUDO presentations and articles
>  - SSH key management
> 4. Applications/3rd party integration
> 4.a. Trusting Microsoft Windows world
> 5. Troubleshooting articles
> 6. Devel docs
> 
> The question is where guides and similar docs fit to this schema. I'm not sure.
> 
> 
> Maybe that this 'task-oriented' structure is good only for beginners, maybe
> that is it wireframe for 'Getting Started page'. I'm not sure...

More task-oriented approach to FreeIPA.org front page and Documentation page
may indeed be helpful. The challenge is indeed in making it task oriented and
still keep it as useful reference for experienced users.

Martin