Documentation overhaul

Jan Safranek jsafrane at redhat.com
Wed Oct 1 12:29:38 UTC 2014


I haven't got much feedback, but in the meantime I polished the chapter
structure, images, links and lot of tiny details in the builder script,
so I think it's ready for alpha release.

Find the documentation at oopenlmi.readthedocs.org and the git repo at
github.com/openlmi/openlmi-doc. The re-build process is still manual,
i.e. I personally must tell rtd.org to fetch new docs from git and
regenerate everything.

If you want to play with it by yourself, clone the git repo and follow
README.md there.

Please look at all the docs and suggest improvements.

Jan

On 09/24/2014 05:56 PM, Jan Safranek wrote:
> We've been busy last weeks with reworking all OpenLMI documentation.
> Initially I wanted to post this announcement when the new docs are
> finished, but with each version I'm finding new problems and tiny
> glitches which need some attention and the finished version is further
> and further ahead.
> 
> So, the work-in-progress version is available at
> http://openlmi-test-doc.readthedocs.org/en/latest/.
> 
> The ultimate goal is:
> - to have it generated by readthedocs.org, as it has nice style (few
> tweaks were needed though and their build system is... hard to tackle with)
> 
> - to have it hosted on doc.openlmi.org, if possible
> 
> - have all documentation (providers, storage, networking, tools,
> scripts) together on one place and linked together (e.g. links from
> providers to appropriate lmi metacommand and back, not done yet)
> 
> - still have possibility to ship the documentation as part of our
> packages (some people prefer offline docs), we'll see if we can achieve
> this.
> 
> - be more newbie-friendly, especially in the overview pages (again, not
> there yet, but 'Storage provider' front page is the first attempt.
> 
> - obsolete some pages on openlmi.org. We'd like all the _documentation_
> to be on doc.openlmi.org, and leave openlmi.org just for overview, some
> tutorials (QuickStart) and integration with other projects (Pegasus SSL
> setup, IPA, ...). All text related to providers, shell or metacommand
> will be removed from there, as it is inconsistent, redundant and often
> completely wrong.
> 
> 
> What's ready for review:
> - overall style (colors, fonts, ...). We believe readthedocs.org has
> done great job in this, I have just added support for four levels of the
> navigation menu on the left
> 
> - overall structure (= the navigation menu)
>   - some chapters have weird name, I know about"
>     - OpenLMI Networking Provider documentation should be just
> "Networking provider"
>     - OpenLMI Tools documentation should be "OpenLMI client tools and
> utilities" or something like that, as it covers lmi metacommand,
> lmishell and OpenLMI scripts.
> 
> - most of OpenLMI providers
>   - except networking
>   - storage should not include "CIM classes" chapter
>   - all providers need better front pages with overview, link to
> appropriate lmi metacommand reference. See storage as example.
> 
> I'm tuning client utilities chapters, adding python API reference,
> individual metacommand, adjusting chapter names etc.
> 
> 
> You can see there is lot of work ahead. You can contribute, best by
> patches to individual git repos (openlmi-providers, -networking,
> -storage and -tools; use reviewboard as usual) or by feedback here on
> openlmi-devel.
> 
> For better docs!
> 
> Jan
> _______________________________________________
> openlmi-devel mailing list
> openlmi-devel at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/openlmi-devel
> 



More information about the openlmi-devel mailing list