Thursday, November 22, 2012

Contributing to the SUSE Studio online help

As you know, we've have a shiny new online help system for SUSE Studio for a while now. One of the good things about it is that you can contribute there as well. It's pretty simple and can be done without leaving your web browser. Here's how:

Finding the page

The first step is to find the page you want to edit in the studio-help repository on Github. That's where we store the sources for the online help. You can simply browse the files there, the structure in the repository is the same as you also find in the actual help.

As an example we'll add some documentation about exporting appliance configuration, where there currently is only a stub page.

Editing the page

Github provides an Edit button on the page where the file is displayed. When you click it some magic happens, the repository gets forked, so you have your private branch of this file now. It also opens an editor, so you can edit page right in your web browser.

We'll add some new content. The format is Markdown, which is a simple text format, which can be read and written by humans as well as computers, e.g. for generation of web pages in HTML.

When you want to see how the markdown will be rendered, you can click the Preview button in the editor and you'll get the text displayed mostly as it will also be shown on the actual SUSE Studio help page.

Creating a pull request

At the bottom of the editor there is a button "Propose file change". Clicking this button will create a patch containing all your changes. Go to the main page of your fork then, and you'll see the patch listed there.

With the "Pull Request" button you can send the change to us to the master repository of the online help, which is used to generate the actual help on

There you go. Your change has been queued for review by the SUSE Studio team.


Publishing the help

When we have reviewed the change, it will go live and be shown as part of the public SUSE Studio online help.


As you see, it's really easy to contribute improvements and content to the online help. So if you see something which can be made better, you are very welcome to help there. It's very much appreciated.

By the way, if you prefer a work flow, where you can use your own environment to edit the files, and you can use the full power of git, you can also check out the sources for the online help from the studio-help repository, edit them locally, and push them with git. It will get same result, but with your choice of tools.

No comments:

Post a Comment

© 2013 SUSE