blogpost connected to #499

on scoping manageable lessons

_posts/2018-02-20-planning-a-lesson.md

@@ -0,0 +1,48 @@
+---
+title: Tips for (finishing) a Good Technical Tutorial
+authors: 
+- Adam Crymble
+layout: post
+categories: posts 
+---
+
+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 bring project ideas that will result in finished lessons that our readers can benefit from.
+
+## Sustainability
+
+We do our best to future-proof our lessons so that readers can benefit from it for many years. You can help with this process by thinking ahead and reading our [Sustainability Guidelines](https://programminghistorian.org/author-guidelines#write-sustainably).
+
+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
+
+We get a lot of lesson proposals, and the thing that unites most of them is ambition. Many of the pitches we receive simply want to do too much: teach an entire programming language, or cover everything one needs to know about a category of research. We love your ambition, but we also know from experience that you've just pitched a series of textbooks, and it isn't feasible. A lesson is best when it seeks to do one thing well. Take a look at our [published lessons](http://programminghistorian.org/lessons/) for a sense of what's possible.
+
+## Multiple Lessons
+
+It's also not uncommon to get offers to write a series of lessons. Once the authors realise how much work that is, the tend to disappear. We know the original Python lessons written by William J. Turkel were a series (17 lessons in fact!), but we can tell you from experience that pitches for multiple lessons almost never turn into multiple lessons. That's not because we wouldn't have them, but because authors are underestimating the amount of effort that goes into producing one, let alone five or six good lessons.
+
+## The Commitment
+
+It may not look like much work, but our tutorials are not blog posts that you can throw together in an afternoon. The 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, lessons 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.
+
+As the commitment required to publish a tutorial is often under-estimated by authors, we like to be up front. 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](https://github.com/programminghistorian/ph-submissions/issues)
+
+## Keep at it
+
+And finally, keep at it. The biggest cause of delay in the publication of lessons comes from authors at the point they receive their peer review feedback. Often these reviews include lists of minor changes that could be knocked off in a few minutes or an hour at the most. But it can look like a lot to do and it's not uncommon for editors to have to chase authors for months (sometimes years).
+
+We all get busy, but please keep in mind that our editors are volunteers, and keeping in communication and being realistic about your commitment helps them focus their energy on committed authors.
+
+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.
+
+## 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](http://programminghistorian.org/project-team) for some initial feedback. We look forward to hearing from you.