Blog post on scoping lessons

[acrymble]

Arising from our #475 call was a notion that new authors tend to come to us with overly ambitious scopes for potential lessons, and that they under-estimate the amount of time and effort that goes into a good lesson.

Rather than updating documentation, would people value a blog post that we could refer people to that gives some perspectives on the above problems, as a means of reducing editorial backlog and lessons that fail to materialise?

[walshbr]

That does seem useful. While each case is different, some boilerplate we can refer people to might be a helpful time saver.

[acrymble]

Proposed text for comment:

---

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. Some 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.

3. Make sure any data required to do the lesson is included as an attachment, stored on our site. This ensures lessons do not break in future when links begin to rot.

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 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

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 for some initial feedback. We look forward to hearing from you.

[mdlincoln]

I really like this text - thanks for working it up @acrymble

However, I think it absolutely belongs on a page in our contributions section, rather than a blog post. As a user, I'd expect everything I need to know about contributing to be contained among the contribution sections, not scattered about in a blog post alongside announcements about new editors, etc.

I also think this language supersedes/replaces some of our current copy in the "Author Guidelines" page. Rather than having conflicting statements, I believe a version of the text Adam has worked up here should go on to the Author Guidelines page under "Propose a lesson"

[acrymble]

@mdlincoln thanks, I definitely don't want to contradict the Author Guidelines.

I'm also not keen to keep asking our Spanish team to translate our set pages, which is why I thought the blog would be better. I suspect they're getting bored of all of the translation requests!

[mdlincoln]

Well, if the hope is to solicit original lessons in Spanish, not just translations, then we'd better have consistent guidelines.

[acrymble]

Maybe this is something we should leave for our new Managing Editor to leave a mark on then?

[mdlincoln]

Closed by #612

[mdlincoln]

sorry - I just noticed that @acrymble wanted to talk about this at the next meeting - I'll provisionally re-open. I think we should figure out if there's anything that needs to be added on now that we have sustainability policies published.

[mdlincoln]

Closed with #722