Suggestions for Creating Step-by-Step Web Development Tutorials for Nettuts+
This article discusses one approach to writing step-by-step tutorials. While the focus here is for NETTUTS, much of the approach can be applied for any site. If you plan to write tutorials for NETTUTS, you should read/browse this article. There's also a parallel article at PSDTUTS that Editor Sean Hodge wrote, which actually inspired this one.
You'll probably have noticed that the most popular tutorials here focus on web dev having a design-y element. So knowing how to use graphics software such as Photoshop or Fireworks might help. At least, know how to get a screenshot, since this is the minimum you want to include in your tutorial for visual elements.
Plan and Have a Checklist
You do not have to get really formal, but you should plan out your tutorial and apply a checklist. Here's a suggested checklist, though feel free to modify it to your liking:
- Plan your tutorial.
- Write up your checklist.
- Research any code libraries, plugins, techniques.
- Decide on your demo code's feature set.
- Write your code, test, and refine it until you're satisfied.
- Write the tutorial text.
- Incorporate your demo code in snippets, in the tutorial (as per our Tutorial Guidelines).
- List any shortcomings of the code that you're aware of. (I.e., doesn't work in Internet Exploder 6.0+, etc.)
- Provide suitable visual elements (image, screenshot, animation, etc.) not wider than 600 pixels.
- Edit the tutorial text and number each section with "Step 1", "Step 2", etc.
- If you have used images that are not yours, you must not only give attribution, you must have either implicit (e.g., CC license on Flickr) or explicit permission to use them. This includes images visible in your tutorial and in your demo.
- Prepare source code for download and ZIP it up. In the same ZIP file, include working demo files.
Make It Easy On Yourself
There are a couple of ways you can go about getting published on NETTUTS. One way is to send your working demo files, source code, tutorial text and images (all ZIPped together) via the form link on the Tutorial Guidelines page. This way, you'll get an answer a lot sooner, but it's a lot of work for you to have done if it's not suitable for NETTUTS. (This is still recommended if you have never submitted a tutorial.)
Make it easier on yourself. Instead of writing up demo code and a tutorial first, pitch an idea first. This is actually recommended if you've previously sent a full tutorial, even if it was not published:
- Come up with an idea and submit that to me via the form link on the Tutorial Guidelines page. (Use a blank ZIP file, since the form requires it.) Or if you have previously submitted an idea/ tutorial to me, you have my NETTUTS email address and you are welcome to pitch me directly.
- If you have not previously written a tutorial for the site, there are a couple of stages:
- Interest in your idea is not a promise of publication. After pitching an idea and getting interest, you will need to show demo code (even if only on your own server).
- If you do the demo code and it's suitable to NETTUTS, I'll ask you - but not request - if you want to write the tutorial, but with no guarantee of publication.
- Note that this sounds unfair but is really no different than if you submit the full tutorial upfront. This way, you have some stages where you can change your mind, reducing your overall effort. If you'd rather send your tutorial and files upfront, that's fine too.
- On the other hand, if you have already written a good tutorial that required little editing, I'm much more lenient. You can pitch the idea, get my go ahead, and write the tutorial.
In either case, if a demo shows potential but the tutorial needs work, I'll try to work with you on a limited basis to improve the text. However, I can't write it for you. A bunch of code snippets and some text that only functionally describes what is happening is not a tutorial.
Make It Easy On the Editor
As the readership of NETTUTS grows, I'll have less time to assess whether a tutorial is suited to NETTUTS. Make it easy on me, make me want to use your tutorial and demo:
- Use your real name and email in the submission. (You must also have a PayPal account so we can pay you.)
- Describe clearly what your tutorial will show, and what your demo code will demonstrate.
- Submit demo code that works and doesn't require me to do a lot of setup (beyond uploading some files to a server).
- Don't send me demo code that requires me to add my own images or something else, especially if you don't bother to tell me upfront. My desire to help you clashes with the lack of time.
- Overall, minimize the amount of time I have to spend setting up your demo code just to assess it. The more effort it takes, the more likely it'll be turned down. (You can always start with a demo on one of your sites, though eventually you'll need to supply files to me.)
Put yourself in my place and think about what makes me want to accept your tutorial. Do not pitch me a series if you have not already had a tutorial accepted and published. The same goes for cross-site series (i.e, Part 1 for PSDTUTS, Part 2 for NETTUTS).
Describe Each Step Thoroughly
Ultimately, the tutorial is for readers of the site, not for me. If the title of the tutorial attracts them, and if they read through the tutorial after viewing the demo or even the initial visual (image, diagram, etc.), then they want to learn. While you do not need to hand-hold and describe every line of code as if a reader has never coded before, you do need to describe the lines of code related specifically to any libraries, plugins or special techniques you're using.
The biggest problem with submissions so far: using a code library or plugin, showing a code snippet but not actually describing the relevant lines of code. Saying, "here's the code to do X," isn't enough. Why would a reader bother with your tutorial if you aren't revealing the how-to?
Tone and Writing Style
Before you submit actual tutorial text, read over some of Collis' tutorials here, as a starting point. While it's good to have your own style, you also have to remember that most site readers have some (or a lot) of web coding experience. Talk to them, not at them. (I'm a verbose type, which comes from having been a college teaching assistant/ lab instructor for non-computer students people taking a mandatory computer course.)
Guidelines and Formatting
There's already a Tutorial Guidelines page, which has a link to a blank tutorial ZIP. Consult this page and use this ZIP template.
Decide on Your Topic
Do you really know what you want kind of tutorial you want to do? Not singling anyone out here, but a few submissions gave me the impression that the person simply wanted the feather in their cap of having been published on a site like NETTUTS. Their tutorial and demo code description was vague, and despite my nudging about what to try, they didn't bite.
One of the best ways to plan and build a tutorial is to sketch out your ideas and outline the features as well as what you are demonstrating. Since NETTUTS tutorials are code-driven, you have the extra requirement of having functional code to present. Here is my preferred process for creating a tutorial - but don't forget the checklist mentioned earlier:
- Brainstorm a few application ideas.
- Research the necessary libraries, plugins, features, limitations, etc.
- Outline desired features, sketch out or mockup browser screens. (Remember, you can use snapshots of the finished mockups in your tutorial.)
- Write the code, test and refine it. (Test in Browsershots, decribed in the next section.)
- Write the tutorial around your code, and incorporate snippets in easily digestible chunks, formatted as per the Tutorial Guidelines.
- Edit the tutorial if necessary. Put yourself in the mind of a reader. If they are consulting your tutorial because the title caught their attention, then they probably don't understand your code without a proper explanation. Don't just show the code block and assume the reader should understand. Otherwise, you are writing code, not a tutorial.
- Add visual elements (screenshots, etc.). See the Visuals section below.
Demo Code and Cross-Browser Issues
While it'd be nice that your demo works in all browsers, that's not always possible. Some code libraries - e.g., jQuery - just do not support older browsers. At the least, your code should work for the browsers that libraries you are using support.
By the way, despite the protestations by way of comments of some NETTUTS readers, Firefox 3 is not in widespread use at the time of this writing. It's also buggy and still a memory hog, according to some Twitter and Plurk users. We'll have to consider browser compatibility on a case by case basis, but try to cover the most recent stable browsers. State if your code does not work somewhere it should, and why that is.
One tool that will help you with cross-browser testing is the site Browsershots, which is an easy way to test your code in multiple (virtual) browsers for Linux, Windows, Mac OS, and BSD.
Unlike with our sister site PSDTUTS, when it comes to web dev tutorials, it's not always easy coming up with sexy images. Still, visuals make a tutorial more interesting, as well as help demonstrate concepts. So visuals in your tutorial are a must, and you might have to get creative. Here are some options:
- Relevant image.
- Screen snapshots of your application in various states of use.
- Screencast of your application in use, or something relevant to your tutorial.
- A diagram or mind map representing some information about your application, its use or its design and creation.
- Relevant video content, maybe even a screencast of your demo code in use.
Incorporate visuals as often and early as possible in your tutorial. Many of the tutorials I've turned down so far had no images whatsoever. It's not that hard to take a screen snapshot of your application in use, or a mockup screen being produced in Photoshop, or whatever is relevant. You do not need dozens of visuals, but even a few judiciously selected screen captures might be enough.
Note: If you use visuals from other sources - either in your tutorial text or your demo - you must have explicit or implicit permission and must cite the source(s). For example, you can use images from a source such as Flickr, under suitable CC commercial license.
Cite Your Sources
In addition to crediting images, make sure you credit any code libraries, sources, etc. This does not mean you can present someone else's code as your own, but rather if you have a large tutorial and use a technique originally presented by someone else, credit them.
In addition to tutorials, we publish one one article per week related to web development. The article contributions are once every other week. Resource articles are good candidates, such as my CSS Grid Frameworks article - though yours doesn't have to be as massively long.
My preference is to accept pitches for articles from people who are experienced writers/ bloggers, though you do not need to have written a tutorial since the style is different.
I try to respond to everyone as quickly as possible, though in some weeks the volume of submissions is high enough that it's easy for me to lose track. Rest assured, I will respond, though you can nudge me if you haven't heard back in a couple of weeks after submitting an idea or tutorial.
I'm looking forward to continued idea pitches and submissions from NETTUTS readers. If you don't know where to start, Collis' tutorials here at NETTUTS and at PSDTUTS are a great model to follow, both in terms of screen snaps, coding and writing style.