Gigi Labs

Please follow Gigi Labs for the latest articles.

Writing Style Guide

The articles in Programmer's Ranch intentionally follow a particular style intended to teach moderately complex programming concepts in simple ways. Below are a few tips for adopting this kind of style. If you want to write an article for Programmer's Ranch, these should serve as guidelines. If you're not, you might still find them helpful.

Be informal

Imagine you're talking to a 5-year-old. Try to make it as clear and as fun as possible. Don't use big words and complex sentences. It should not end up looking like a scientific paper.

Demonstrate

Don't just talk. Illustrate your point with code, screenshots and references to third party sources.

Practice before theory

First demonstrate your point, and then explain the moral of the story. Avoid rambling about the benefits of Test Driven Development until you've shown it at work. The typical style of PowerPoint-first-demo-after is exactly what you want to avoid.

The practical aspect should be demonstrated step by step so that readers may follow along and reproduce it. Show output with your code so that readers can correlate code and results in their minds.

Be simple

When using examples, pick those that are most likely familiar to just about everyone - classic games (Pong), common problems (splitting strings), etc. When you give examples such as helicopter components or widgets, many people may not be able to follow along. When you present analogies such as skiing or dojos, many people might not be able to correlate.

Be concise

Articles should cover just enough knowledge to demonstrate the subject of the article. We don't want to be encyclopaedic and explain every class in a namespace, or every method in a class - there are plenty of sites for that kind of thing. We want to avoid being like certifications, in which you spend ages covering an entire field when in fact you'll use about 10% of it in practice. Remember: more beef, less bull.

Be brief

If your article is too long, people won't really read it. as much as possible, keep articles short and start fresh examples for each. It is acceptable to continue an article in a second part if it teaches something different, but as far as possible don't split it into too many parts. I've violated this myself with the Space Invaders series, but that doesn't mean it's a good thing.

No comments:

Post a Comment

Note: Only a member of this blog may post a comment.