How To Write A Software Guide For Open Robotics
with Devon Ash
Published At 2015-05-28 18:25:02
How To Write A Software Tutorial/Guide
By Devon Ash
So you want to make a tutorial?
Ideally, you want to be bringing in new knowledge to the team, some cool tips/tricks for solving something, or by simplifying some other process with the contribution of a software guide or tutorial. This tutorial will show you how to write a software tutorial! This will be useful for everyone to know on the team so we can all become more autonomous in helping each other out, to found our knowledge, and be able to point new members to documents that we write so we don't use up our own time.
First things first, you'll need an account on the Open Robotics website. Once you have one, make sure you have access to "Manage Postings"
and then "Manage Training".
If it's not there, ping J. Chapple or B. McNeil about access issues. Not only will I show you how to make the tutorial physically, but some tips on making it better (and you can add whatever you need to make it better as well!)
1. Get a software training module skeleton
The software skeleton can be found at http://openrobotics.ca/manage/training/post/?id=28 which is the management page for the "Skeleton For Software Training Modules". Copy and paste the html text inside the content box (which is inside the link), you'll need it for later
2. Create a new training module post
Now go into the "Manage Postings" and "Training Modules" once again. This time, on the left, you'll see a button to create a new post.
Create a post, fill in all the details of the post, and copy and paste the html text into the box. Make sure you check "Make post visible"
and then click "Update post".
Then, you can use the "View post button".
I tend to open it in another tab so I can continue working on the html.
3. Modifying the guide contents
In the HTML, you'll read through and see places that exist to put the header, a header image, and base content. Below that, there is a comment specifying the end of the content and the beginning of the resources and references. I'll talk about that for a moment. The resources and references section can help the reader learn more about the subject and find other resources other than your own. It will also help you understand what else exists in the world and measure up against their quality/information content provided.
The required reading section should list books, papers, or tutorials that talk about the content you mentioned in the guide. The required exercises section points to exercises, commands, or programs/code that have been written which will help the reader learn about the concepts you've presented. Extremely useful, as it is very hard to grasp a concept from just one guide. The users will be successful if they have an opportunity to play with many (and acts as a failsafe as things move around on the internet and one tutorial might not work anymore). I usually do a couple google keyword searches to find more about the topic, look around on Github, and so on.
Additional resources are things you find cool that are relevant to the topic discussed in the guide. The juicy stuff is existing implementations of the concept. This is concrete, executable code most of the time. This will help you learn the structure and how to solve relevant problems. It'll make you generalize the concept so it will be easier to implement in your own. Remember, most of the stuff in the world is just copypasta and it is truly rare to ever develop something from scratch. It's best to learn from others mistakes/implementations, and then fail where there are new developments being made
The other tutorials section points at other tutorials about the same topic that the user may want to follow
4. Spicing your tutorial up with picture waypoints
Installing Shutter on Linux/Windows is a great way to capture small portions of your screen which can be used later in a tutorial. Images are really powerful at demonstrating what to do for a user, so they can follow long either by image or text, or clarify something by looking at an image.
5. Getting Publicity
You've spent a lot of time writing a long tutorial that is carefully edited and has a lot of new knowledge. It's time to tell the team, mainly the social media team, about your cool work. This will help engage new members, show everyone how awesome and fun you are, and get exposure so that the information you wrote gets used. Some of the places I like to post new blogs are:
- a personal blog
- Opbots internal facebook group
- Opbots external facebook group
- The ROS wiki
- The blog section of Open Robotics
(Optional) 6. Understanding a "growth" workflow
What is a growth workflow? It is the process of planting a seed and seeing it grow into an excellent and healthy tree. Since we're software engineers, we deal with information a lot and not seeds. In this metaphor, our seeds are the code we write and contributions we make to the robot/community. If you understand the growth work flow, it will make sure that Opbots continues to grow, and actually, anything you do is that much more successful. So what is it?
Basically, the way you do something in a team organization should look like this:
- Contribute code/document/executable
- Pretty-up the contribution to make it usable by others
- Write a guide on how to use that stuff you just made
- Make sure everyone knows about the stuff you just made and how to use it
- Get feedback on it and improve it
- Maintain what you have so it stays around for a long time, re-iterate between step 5 and this step.