Four-page tutorial

From Writer's site

Jump to: navigation, search

Linux Format writer's templates

Four-page tutorial

Click here for the template in plain text


1 PURPOSE:
All tutorials should be based on a project. The reader should be able to start at the beginning and feel like they're accomplished something by the end. Use the header and the standfirst to let the reader know what it is they'll be learning how to do, then fulfil that promise in the body of the tutorial. NB "A guide to XYZ" isn't good enough; "Build something with XYZ" is much better.

2 WORD COUNT:
Approximately 2,900 words of body copy, plus three boxouts of approx 180 words (that's a total of 3,440 words).

Ideas for boxes:
  • Grabs with their own commentary.
  • A small step-by-step guide.
  • A tabulated list of resources or instructions.
  • Essential system requirements.
  • Facts about the product.
  • Background information or history.
  • A mini project.
  • If your tutorial has a lot of code in it, aim closer at 2,500 words than 2,900. Please try to limit the amount of code you use; it's not very pretty to look at or nice to read. We recommend a maximum of about 12 lines of code in any one block. If the tutorial needs more code than that we can put it on the coverdisk, but in this case it will not count toward the tutorial wordcount.


3 LAYOUT:

  • If there's anything you need to point out to design and production staff, label it ///DESIGN NOTE/// and put it IN CAPS at the beginning of the text in square brackets, or at the relevant point in the body if it refers to something like an annotated pic or flow diagram.
  • If you would like to present your tutorial as a series of screengrabs and long captions, rather than as long narrative text with screengrabs on the side, please see TutorialSteps_template or check with LXF staff and request a word count.

4 PICTURES AND BOXES:
You must provide two or three Quick Tip boxes. Each box must contain a single tip relating to the software and the tutorial in hand. The total word count can be 20-50 words. Just text, no images.

In addition, please provide about five images.
Notes about images

  • Images should be colour, and 250 DPI. Screengrabs are best sent in PNG format. If you can't avoid using images of the console, please try to use a colourful text editor or X terminal, and include some of the desktop's colourful background before you crop it.
  • All screengrabs should be named appropriately with something relevant to the article's title, numbered sequentially in the order they are to appear in the article if relevant, and all should have a proper caption.
  • Captions must be interesting. A good caption contains some titbit of information that has been held back from the body copy. Captions are also usually an appropriate place to exhibit a bit of wit, and it's encouraged!

NB "Fig 1: the configuration editor" is not good enough.

  • Avoid grabs that have copyrighted images as your desktop wallpaper, or grabs that include images of your pets or children. Also avoid taking grabs of the Linux Format website.

Also consider submitting diagrams or charts. We can redraw them in-house.







5 STRUCTURE:

///TOP BAR///
Tutorial Xxx
Where Xxx is the name of the series or, if it is a one-off tutorial, the name of the software/technology being used.

///TITLE///
Please enter the name of the software/technology being used, then a colon, followed by what the reader will do in the tutorial.
eg
Security: Harden your passwords
Greasemonkey: Mod the web!
Inkscape: Design a web page

///STANDFIRST///
Part x: [If it is part of a series] followed by 15-20 words to introduce the tutorial and the author's name. Aim to get across what techniques the reader will learn or be using, and some enthusiasm about the project, and use humour if you like.

///ON THE DVD LOGO///
We try to put most free software used in tutorials on to the LXF coverdisc. Please contact the disc editor as soon as possible to let him know what you are reviewing and where the code is kept online so that he can take a look. Email mike.saunders@futurenet.co.uk.

///FOOTNOTES///
Use these if your tutorial is part of a series:
Last month xxxxx
eg Last month We built a kid-friendly desktop with restricted access and web filters.
Next month xxxx
eg Next month We'll bring in data from other sources and try queries and reports. ///END FOOTNOTES///

///OUR EXPERT BOX///
yourpic.png

If you have written for us recently, we probably have your biographical details already. If not, this is the place where you should write 25-30 words on your background, introducing yourself to the readers and letting them know why you are qualified to write this tutorial!
///END OUR EXPERT BOX///

///BODY COPY///
[Add tutorial copy here.]

Body copy notes:

  • Any code must be clearly tagged at the start with ///CODE/// and at the end with ///END CODE/// because we format it differently in the magazine. Any indents in code MUST be done with spaces, NOT tabs. A good rule-of-thumb replacement for tabs in pasted-in code is to use two spaces: the code is quite often displayed in quite narrow columns.

///CROSSHEAD///
A one-line title that:
a/ breaks up the dense text of the main body copy
b/ highlights an important point or a new section.


///PIC///
yourfilename_number.jpg

///CAPTION///
10-20 words.

///PULL QUOTE///
An interesting quote of 10-15 words from your tutorial.

///COMPULSORY BOX///
///BOX TITLE///
Quick tip

///BOX BODY///
The text of your box.
///END QUICK TIP///

///OPTIONAL BOX///
Optional box notes:

  • If you include pics in a box, include their filename with a ///PIC/// tag, and a caption with a ///CAPTION/// tag, as you would in the body text.

///BOX TITLE///
This should make it clear what the box is about.
eg Resources

///BOX SUBHEAD///
This shouldn't be necessary unless the box title needs embellishing to make sense.

///BOX BODY///
The text of your box.

///BOX CROSSHEAD///
Only necessary for big boxes.

///END BOX///

///END BODY COPY///

Personal tools