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

Tue Oct 22 14:42:11 UTC 2013

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

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

>>> - merge "Additional Resources" section with "FreeIPA Training Series" section
>>> and "Public Presentations" section
>>
>> How FAQ or HOWTOs relate to Training Series or Public Presentations? Or you
>> just meant placing them close together?
>
> I also failed to understand this, they are completely different
> categories.
>
> The videos and presentations are for people that want generic info. The
> HowTo/Faqs are for peopl that have a specific problem and are looking
> for a solution.

Exactly. That is what I proposed below - separate sections 'marketing' (high 
level stuff) and 'get your hands dirty' (the useful stuff). See below.

>>> - pull all how-tos to "/Documentation"
>>
>> I am not sure that placing all these articles directly to /Documentation would
>> make it simpler. I understand /Documentation rather as a focal point of all
>> documentation, which can lead you directly to the information you seek.

I can see you point. The reply to this matter continues at the end of e-mail, 
I noticed that you wrote some other points about how-tos there.

> They should be in a Troubleshooting section at most, but they are
> clearly Documentation.

I'm not following you. How is "How to configure Zimbra" related to 
"Troubleshooting"?

>>> I don't think that users care about distinction between "Additional
>>> Resources"/"FreeIPA Training Series"/"Public Presentations" section. The
>>> differentiation could be more about 'marketing' and 'get your hands dirty'
>>> categories.
>>
>> Makes sense. We can switch from User Documentation/Developer Documentation to
>> this distinction.
>
> This sounds like a good improvement.
>
>>> Reorganize how-tos:
>>> My intention is to have all articles related e.g. to 'Zimbra' linked from one
>>> place, all articles about NFS from another place etc. I don't have much
>>> experience with "sub/categories" in Wikimedia, but I hope that we can create
>>> something like this:
>>> http://en.wikipedia.org/wiki/Category:Cryptographic_algorithms
>>
>> We can, if it makes sense. We can simply mark the howtos with categories and
>> mediawiki will do the rest.
>>
>> Did you check the HOWTO page lately? I did a bit of reorganization there last
>> week, grouping HOWTOs to sections, like "Mail Services" - this should help the
>> grouping you have in mind.
>
> Nice work!

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

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

-- 
Petr^2 Spacek