[Freeipa-devel] Planning FreeIPA Upstream Doc changes

[Martin Kosek]

On 08/08/2013 04:53 PM, JR Aquino wrote:
> 
> On Aug 8, 2013, at 12:19 AM, "Martin Kosek" <mkosek at redhat.com> wrote:
...
>> B) Add a new git tree to FreeIPA fedorahosted account (freeipa/docs.git) and
>> release the docs asynchronously to the code (there could be of course a
>> preliminary version on FreeIPA.org site). I was already thinking about options
>> to seamlessly integrate an RPM with docs to FreeIPA Web UI which could then
>> provide relevant help links from the UI dialogs to the right spots of
>> documentation.
>> - so far, it seems that option B) will get us more flexibility and would avoid
>> people contributing to the code only downloading also the doc.
>> WHEN: this step would be right after the plan is acknowledged
> 
> ^ +1
> 
> And I agree that a preliminary should be hosted on the FreeIPA.org project portal rather than the fedora documentation site. It feels more natural that way.
> 
> Ideally, it should be trivial to check out or grab the relevant rpm for a given version as we move forward into new releases, that way an admin can view the doc that refers specifically to their running release rather than be confused about up-to-date features that may not exist on theirs.

In the beginning, there will be just a _version_ documentation on FreeIPA.org.
Admins could then easily read the version that's relevant to them or download
it in a format they like.

Later we can bells and whistles and start releasing RPM you could install along
with your FreeIPA (we are already discussing means if integrating doc with Web UI).

...
>> 3) Host the result on FreeIPA.org
>> - we used to release to Fedora documentation portal, but I am thinking it would
>> be more natural to host a project site on project portal instead of Fedora
>> Documentation which rather holds general Fedora infrastructure books. It may be
>> also more intuitive for users to find it on FreeIPA.org than on Fedora docs.
>> - we can take advantage of publican and build a doc site like
>> "docs.freeipa.org" which would held publican-managed doc site with our guides.
>> I tried to play with publican and this is a first PoC result:
>> http://mkosek.fedorapeople.org/publican_site/
>> - I would prefer if our generated user guides (including current Extending
>> guide hosted on abbra.fedorapeople.org site) use Docbook + be integrated in the
>> site + wiki to have them all under the same roof with consistent look
>> WHEN: Before FreeIPA 3.4 is released
> 
> ^+1
> 
> I've always found it a little awkward to hunt docs down at the fedora documentation portal.

Good! Then it seems as a good decision.

Thanks for response,
Martin