Re: [Freeipa-devel] FreeIPA.org/Documentation improvements: request for comments
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
[Freeipa-devel] FreeIPA.org/Documentation improvements: request for comments
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
