[Freeipa-users] FreeIPA 3.1.5 User Guide published!

[Martin Kosek]

On 06/25/2013 10:12 PM, Justin Brown wrote:
> I'm also a big fan of the documentation and reference it frequently.

Good!

> I know that documentation is not release notes, but it would be nice to have
> some relation between the two. Two ideas:
> * If the docs are released at the same time as the software, the release notes
> should include links to the relevant sections of the documentation.

Since last 3.2 I started to add links from enhancements to relevant design 
pages in FreeIPA.org wiki (http://www.freeipa.org/page/V3_Designs). But I will 
also think about some nice way to map new features to documentation.

> * For particularly large features, it may make sense to put a *temporary* note
> that feature X is new in version Y (and the note would be removed in Z or Z+1).

Hm, interesting idea. We will think about that in next doc release.

> The second idea is taken from Python's documentation and how they do an
> excellent job of specifying when certain features were added. Now, FreeIPA
> doesn't have near the varying number of versions and legacy environments that a
> programming language has. That's why I wouldn't want tags like "added in 2.1.0"
> still hanging around.
>
> Lastly, the documentation needs some release notes of it's own. The document
> change history isn't that useful. Two ideas:
> * A better "what's new in the docs" page that specifically links to new sections.
> * Asterisks or some other markup on the table of contents that mark links that
> have substantively changed.

Hmm, I think that asterisk-ing fixed sections (updated content) would not be so 
useful and would add more work for people updating the sections. What I think 
that would be interesting is to have links to new sections - but this should be 
exactly covered if we add documentation links to new features in FreeIPA 
release notes.

> A user browsing the table of contents may become interested in checking out a
> new feature since she knows that the typical high-quality FreeIPA documentation
> is right there to help.
>
> How would the freeipa-docs package work? PDFs in a directory or would they be
> accessible from my FreeIPA web interface? I would definitely be interested in
> the package if its the later. Otherwise, I'll probably stick to the Fedora Docs
> website.

Yes, I was thinking that freeipa-docs could add PDFs or browseable HTMLs (like 
the one on Fedora docs site) to appropriate places in /usr/.

But having the documentation accessible from FreeIPA web interface is 
definitely an interesting idea which would also not be so difficult given that 
it is easy to generate HTML site our of the FreeIPA guide. I filed an upstream 
ticket with this RFE and wrote down what we found out:

https://fedorahosted.org/freeipa/ticket/3753

> Excellent work. Thanks Deon and company.
>
> Lastly, Fedora 19 is nigh upon us. Time to dive right back into the fire.
>
> Cheers,
> Justin

Thanks!
Martin

>
>
> On Tue, Jun 25, 2013 at 2:10 PM, Andrew Tranquada
> <andrew.tranquada at mailtrust.com <mailto:andrew.tranquada at mailtrust.com>> wrote:
>
>     I am aware of the documentation and have found it invaluable so far, one
>     of the better documented projects out there.
>     Personally, I would love this guide released frequently and  really like
>     the idea of having the documentation in a sub package.
>
>     Thanks!!!
>
>
>
>
>
>
>     On 6/25/13 12:07 PM, "Martin Kosek" <mkosek at redhat.com
>     <mailto:mkosek at redhat.com>> wrote:
>
>      >Hello,
>      >
>      >The FreeIPA Team has published a User Guide for FreeIPA 3.1.x series
>      >introduced
>      >in Fedora 18:
>      >
>      >http://docs.fedoraproject.org/en-US/Fedora/18/html/FreeIPA_Guide/index.htm
>      >l
>      >
>      >Big thanks to Deon Lackey who was the main contributor for this docs!
>      >
>      >On a side note, FreeIPA team is in process of re-considering and
>      >improving our
>      >user/development documentation and I am just curious - are FreeIPA users
>      >well
>      >aware of this documentation, do you use it frequently when you seek
>      >FreeIPA
>      >related information? Any ideas for improvements?
>      >
>      >Do you want to continue us to release this guide frequently with FreeIPA
>      >releases? For sake of future, we are also considering releasing this User
>      >Guide
>      >right during FreeIPA release, in a special subpackage (e.g. freeipa-docs).
>      >
>      >Thanks for any feedback.
>      >
>      >--
>      >Martin Kosek <mkosek at redhat.com <mailto:mkosek at redhat.com>>
>      >Supervisor, Software Engineering - Identity Management Team
>      >Red Hat Inc.
>      >
>      >_______________________________________________
>      >Freeipa-users mailing list
>      >Freeipa-users at redhat.com <mailto:Freeipa-users at redhat.com>
>      >https://www.redhat.com/mailman/listinfo/freeipa-users
>
>
>     _______________________________________________
>     Freeipa-users mailing list
>     Freeipa-users at redhat.com <mailto:Freeipa-users at redhat.com>
>     https://www.redhat.com/mailman/listinfo/freeipa-users
>
>
>
>
> _______________________________________________
> Freeipa-users mailing list
> Freeipa-users at redhat.com
> https://www.redhat.com/mailman/listinfo/freeipa-users
>