I'm also a big fan of the documentation and reference it frequently.

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

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.

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.

Excellent work. Thanks Deon and company.

Lastly, Fedora 19 is nigh upon us. Time to dive right back into the fire.

Cheers,
Justin


On Tue, Jun 25, 2013 at 2:10 PM, Andrew Tranquada <
andrew.tranqu...@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" <mko...@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 <mko...@redhat.com>
> >Supervisor, Software Engineering - Identity Management Team
> >Red Hat Inc.
> >
> >_______________________________________________
> >Freeipa-users mailing list
> >Freeipa-users@redhat.com
> >https://www.redhat.com/mailman/listinfo/freeipa-users
>
>
> _______________________________________________
> Freeipa-users mailing list
> Freeipa-users@redhat.com
> https://www.redhat.com/mailman/listinfo/freeipa-users
>
_______________________________________________
Freeipa-users mailing list
Freeipa-users@redhat.com
https://www.redhat.com/mailman/listinfo/freeipa-users

Reply via email to