Share your knowledge to help shape the Ubuntu app developer site
As we build the app developer site, we want it to grow with content that is useful to app authors. And for that we need your help. Are you familiar with a particular language or tool? Have you written an interesting piece of code that could be useful to others? Have you created a presentation on how to get started with a particular technology? All this and more are useful material for app developer tutorials.
Here’s a guide on how you can contribute to the site by submitting your tutorials and sharing your knowledge with other app developers.
Writing a tutorial
The purpose of these guidelines is to help you write tutorials that are clear, consistent and easy to follow by a wide audience of app authors. They are not exhaustive, just a resource to help you write excellent learning materials. A few general points to remember are:
- Keep it simple
- Assume nothing
- Be consistent
- If you don’t know, ask
- Write with a light and upbeat tone
- Use a spell-checker to ensure there aren’t any typos before submitting your tutorial
- Use standard English
- Use straightforward language that is unambiguous
- Remember that the tutorial will be read by non-English native speakers. Use plain English, without fancy words
- Your tutorial might be modified by the site editors to comply with the guidelines
Each tutorial should have at least the following sections:
- Introduction: here you can explain what the tutorial is about (i.e. the topic) and what audience it is intended for (e.g. novice, intermediate or experienced programmers)
- Requirements: here you should list which Ubuntu stable version the tutorial is targeted for, and which components should be installed to follow it. When possible, use only components that are packaged and available from the Software Centre, and use apt-style links in the form of http://apt.ubuntu.com/p/<packagename> to ease the installation by the audience. Only use PPAs if you absolutely require a version of a component that is not in the stable release (e.g. if you need a new feature or if the version in the PPA fixes a known bug).
- Conclusion: here you can recap what you’ve shown and what can be learnt from the tutorial
- Learn more: here you can add links to additional information related to the subject, so that those with an interest in learning more can explore further.
Some additional recommendations:
- Packages only: use stable, packaged versions of the development tools required to run your tutorial. Do not use components that need to be compiled. Everything needed for the tutorial should be installable from a package.
- Code samples: optionally, provide real code samples. Use Launchpad junk branches: they are ideal for people to easily explore, download, modify and learn.
- Visuals: if possible, add screenshots or videos to make your tutorial more engaging to readers.
- Learn from others: check out the existing tutorials to learn how other authors have written their articles.
Submitting a tutorial
We are currently working out the best way to submit tutorials using the app developer site directly.
For now, if you are interested to write a tutorial or if you have already written some material that you would like to use as a tutorial, contact David Planella by e-mail. Alternatively you can contact him as ‘dpm’ on IRC or through other means on his Launchpad profile, and he’ll make sure it is published.