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

_______________________________________________
Freeipa-devel mailing list
Freeipa-devel@redhat.com
https://www.redhat.com/mailman/listinfo/freeipa-devel

Reply via email to