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.tranqu...@mailtrust.com <mailto: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
    <mailto: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 <mailto:mko...@redhat.com>>
     >Supervisor, Software Engineering - Identity Management Team
     >Red Hat Inc.
     >
     >_______________________________________________
     >Freeipa-users mailing list
     >Freeipa-users@redhat.com <mailto:Freeipa-users@redhat.com>
     >https://www.redhat.com/mailman/listinfo/freeipa-users


    _______________________________________________
    Freeipa-users mailing list
    Freeipa-users@redhat.com <mailto: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