So you’ve got an idea for a tutorial, and you’re excited to share it with the readers of the Programming Historian. This post outlines a few tips for how to sculpt that idea into a manageable and sustainable lesson, while also giving a sense of the level of work involved. We hope that this will help our authors at those early stages of the process, and encourage them to sculpt project ideas that will result in valuable finished lessons that our readers can benefit from.
Sustainability
You will put a lot of work into your tutorial, so the last thing you want is for it to become dated or obsolete. To make sure your efforts have a long-lasting effect on the field, you can take steps to future-proof your work. We have put together some Sustainability Guidelines to help authors think through that process and write defensively.
Some additional ideas include:
1) Link to Wikipedia for any technical terminology and jargon. The folks at Wikipedia will keep the definitions up to date for you.
2) Try to pitch lessons that are not overly dependent upon specific software or user interfaces. These lessons inevitably break or need substantial revision when a new version comes out. Teaching concepts rather than ‘click on the X button’ helps make for sustainable tutorials.
A Manageable Scope
Programming Historian authors are nothing if not ambitious. That’s great, but sometimes we receive pitches for lessons that simply want to do too much, such as teach an entire programming language, or cover everything one needs to know about a category of research. Some of these ideas would make better textbooks than tutorials. If you are too ambitious with the scope of your lesson, chances are you’ll have trouble writing it. A good lesson does one thing well. Take a look at our published lessons for a sense of what’s possible.
Multiple Lessons
One solution to a broad scope is writing multiple lessons, or a series of lessons on a related topic. We are open to this idea in principle, but if this is your first tutorial with the Programming Historian, we would encourage you to start with one lesson in the first instance. The process will be new to you, and it’s a good idea to go through it before making a wider commitment. In our experience, multiple lessons tend not to materialize, or the scope is cut down considerably through the editorial process. That’s because writing a good tutorial is a lot of work.
The Commitment
It may not look like much work, but our authors put a lot into their lessons. These are not blog posts thrown up online after the first draft. Your actual time commitment is probably closer to that required to write up a journal article (minus the research stage). It takes a lot of experience and fresh eyes from lots of people to make sure every step of your lesson contains enough detail (in a logical order) for a novice user to be able to teach themselves the skills needed.
To ensure this, your lesson will undergo a series of revisions, starting with initial feedback from the editor, followed by formal peer reviews. We like to be as quick as possible with this, but we don’t like to rush things (and we have to be sensitive to the fact that both editors and reviewers are volunteering their time). You can expect the whole process to take between 3 and 6 months (longer if you take extra time to revise). This effort can be reduced by ensuring you have written a lesson that has a manageable scope, as noted above. By building time into your schedule for revisions and responding to editors and reviwers promptly, you can help us to work with as many authors as possible, benefitting the entire community in the process.
If you want to get a real sense of what the review process looks like, take a look at some of the entries in submission
Keep at it
And finally, keep at it. We want to make sure that authors’ initial hard work submitting a draft doesn’t go to waste. By understanding the time commitment involved, authors can better focus on managing their scope and expectations about time commitment.
Get in touch
We hope that gives you an idea of what it takes to write a great tutorial. If you’re still interested, please email your idea to our managing editor for some initial feedback. We look forward to hearing from you.
About the author
Adam Crymble, University College London.