satis egitimisatis egitimitengda.pro

Open@Blog

Discussion on the state of cloud computing and open source software that helps build, manage, and deliver everything-as-a-service.

  • Home
    Home This is where you can find all the blog posts throughout the site.
  • Categories
    Categories Displays a list of categories from this blog.
  • Tags
    Tags Displays a list of tags that has been used in the blog.
  • Bloggers
    Bloggers Search for your favorite blogger from this site.
  • Login
Subscribe to this list via RSS Blog posts tagged in documentation

Migration from Publican to Sphinx and Read The Docs

When we started with Cloudstack we chose to use publican for our documentation. I don't actually know why, except that Red Hat documentation is entirely based on publican. Perhaps David Nalley's background with Fedora influenced us :) In any case publican is a very nice documentation building system, it is based on the docbook format and has great support for localization. However it can become difficult to read and organize lots of content, and builds may break for strange reasons. We also noticed that we were not getting many contributors to the documentation, in contrast, the translation efforts via transifex has had over 80 contributors. As more features got added to CloudStack the quality of the content also started to suffer and we also faced issues with publishing the translated documents. We needed to do something, mainly making it easier to contribute to our documentation. Enters ReStructured Text (RST) and Read The Docs (RTD).

Choosing a new format

We started thinking about how to make our documentation easier to contribute to. Looking at Docbook, purely xml based, it is a powerful format but not very developer friendly. A lot of us are happy with basic text editor, with some old farts like me mainly stuck with vi. Markdown has certainly helped a lot of folks in writing documentation and READMEs, just look at Github projects. I started writing in Markdown and my production in terms of documentation and tutorials skyrocketed, it is just a great way to write docs. Restructured Text is another alternative, not really markdown, but pretty close. I got familiar with RST in the Apache libcloud project and fell in love with it, or at least liked it way more than docbook. RST is basically text, only a few markups to learn and your off.

Publishing Platform

A new format is one thing but you then need to build documentation in multiple formats: html, pdf, epub potentially more. How do you move from .rst to these formats for your projects ? Comes in Sphinx, pretty much an equivalent to publican originally aimed at Python documentation but now aimed at much more. Installing sphinx is easy, for instance on Debian/Ubuntu:

apt-get install python-sphinx

You will then have the sphinx-quickstart command in your path, use it to create your sphinx project, add content in index.rst and build the docs with make html. Below is a basic example for a ff sample project.


 
 
 

What really got me sold on reStructuredText and Sphinx was ReadTheDocs (RTD). It hosts documentation for open source projects. It automatically pulls your documentation from your revision control system and builds the docs. The killer feature for me was the integration with github (not just git). Using hooks, RTD can trigger builds on every commit and it also displays an edit on github icon on each documentation page. Click on this icon, and the docs repository will get forked automatically on your github account. This means that people can edit the docs straight up in the github UI and submit pull requests as they read the docs and find issues.

...
Hits: 10292
Rate this blog entry:
Continue reading Comments

Doing it Twice? Write it Down!

Posted by on in Cloud Best Practices

There’s a great meme going around about geeks and repetitive tasks. Because geeks will often get annoyed at the effort of doing something manually, they often decide to find a way to automate it – which usually involves a lot more effort than doing it the one time but “geeks win, eventually” because they save time in the long run.

But in the long run we’re all dead. Then what? Who knows how to run your script? What happens when it needs to be maintained? As Jon Udell points out, it’s really not a contest, it’s a process, and non-geeks can play too. Which is why you should also write it down if you’re going to do it more than two times.

OK, “doing it more than two times” is a huge generalization. What I mean more specifically is:

  • If you’re in a team environment or doing work that will keep cropping up.
  • If you’re doing a task that is non-obvious and/or has a complicated series of steps that is non-obvious to people who are not you.
  • If you’re in any kind of critical path that would block shipping or operations if you aren’t there to do the magical things you do.
  • If you want to reduce your project or organization’s Bus Factor (help other people become proficient).
  • If you want to better understand what you do and how you can improve it.

Then you need to take a step back and document the things that you do on a regular basis, because it will help your teammates and (most likely) even you when you come back to a task that you haven’t done for a long time.

Naturally, I’m thinking of this in terms of a project like CloudStack where documentation is vitally important. The success of a distributed team depends a great deal on good documentation.

...
Hits: 22202
Rate this blog entry:
Continue reading Comments

Open@Citrix

Citrix supports the open source community via developer support and evangeslism. We have a number of developers and evangelists that participate actively in the open source community in Apache Cloudstack, OpenDaylight, Xen Project and XenServer. We also conduct educational activities via the Build A Cloud events held all over the world. 

Connect