Writing Style Guide - Submitting Content

So you’re interested in writing for us — great!


New articles and tutorials need to match the writing style guide and tone of existing Community Learning Center.


Writing Style Guide

Go ahead and take a look at these guidelines.

Content

The introduction to your guide should focus on two things:

  • What your reader will accomplish by following it
  • Why they would want to

Example use case scenarios are great introductory material. Here’s an example of an article with a great introduction.

Introduction

As technology moves forward and becomes the domain of the ordinary individual, Object Oriented Programming has also gained a considerable amount of popularity. CodeIgniter is an excellent example of a program increasing such demand, and to make it even better, and it is a lightweight PHP web application framework. What does that mean for you exactly? Because CodeIgniter is, in fact, a PHP application, it does not necessarily need to install on your personal/local machine. Instead, install it on a VPS server that utilizes a PHP plug-in, meaning it can be used remotely or locally, depending upon the level of skill you have as well as your preferences.

In addition to using a Model-View-Controller for better presentation, CodeIgniter uses Clean URLs, meaning you won’t have to worry about those disaster URLs from the ’90s. All of this, of course, depends upon your ability to install the program. Most tutorials would work under the assumption that you've already finished installing the program, but we are going to cover all the bases so that you don’t have to hunt for installation tutorials around the web.

After the introduction, your guide should be 90% instruction and 10% explanation. Jump into the nitty-gritty, and provide just enough “Hmm, what’s this?” for people who aren’t familiar with the technology. If you want to, you can add an About Technology X section that goes into more theory and background, but the majority of the article should be free from tech rambling.

Aim for an appropriate level of technical difficulty. For example, an article about mail clients should be beginner-friendly, while an article about load-balancing across multiple servers can assume more sysadmin experience. Still, even in more advanced pieces, don’t skimp on the instructions. You can always link to different articles for those who need it, so you don’t end up on a rabbit trail away from your main topic.

Instructions should be straightforward, technically accurate, and thoroughly tested. Skip shortcuts and err on the side of clarity, security, and best practices.

Tone

The tone we use in the Library is friendly and informational — the kind you would use to explain something to a friend, while still getting down to business. A little informality is encouraged, but make sure you use proper spelling and grammar.

Use short, direct sentences, especially when you’re writing a single step in a set of instructions.

Be concise.

Formatting

First, a few housekeeping points about file types:

  • Use PHP Markdown Extra or plain text formatting
  • Submit your final article as a Markdown file (.md) or plain text file (.txt)

Section titles should provide an at-a-glance outline of the article. Just by reading the table of contents, a reader should be able to grasp all the topics in the article and click to jump to the most relevant section. If you use subsections, make sure you have at least two titles that belong in the lower level.

Create section titles like this:

1  2  3  4  5  6  7  8  9  10  11  12
 
# Section 1     Some text.    ## Subsection 1       More text.    ## Subsection 2     Final text.

When you provide step-by-step instructions, list them as numbered steps. Each task, even small ones, should get its own number.

1  2  3
 
1. First step.  2. Second step.  3. Third step.

Use bold text for the names of links, buttons, variables, and other text you point out to the user. Use italic text to introduce new terms. Use inline code blocks for code samples.

1  2  3
 
**bold**  *italic*  `unformatted`

If you’re writing about software with a GUI (graphical user interface), please include images (.png or .jpg). The maximum width for an image is 650 pixels. If you have a larger image, send the original and the resized version. The text for including an image is as follows:

1
 
[![Image description](/docs/assets/image-resized.png)](/docs/assets/image.png)

If you reference outside materials, provide a link:

1
 
[link text](http://example.com)

You can find more formatting instructions and detailed examples on the PHP Markdown Extra website, but the tips above should be enough to get you started!

Topic List and Submission Instructions

Send article submissions to [email protected]. For more instructions, and to see a topic list, please visit the Community Tutorial Suggestions And Ideas.

Thanks for writing to us! We hope to hear from you soon.