So you want to be a code writer?

The following statement are the guidelines for those who want to write an Arduino Code Tutorial. Currently, I’m starting to read about how to write code, and I found this text interesting because it describes how the code language works. HOW THE CODE LANGUAGE TALKS AND THINKS.

So you want to be a Code writer?

Write in the active voice.

Write clearly and conversationally, as if the person following your instructions were there in the room with you.

When giving instruction, write in the second person, so the reader understands that she’s the one who’ll be doing it.

Use short, simple, declarative sentences and commands rather than compound sentences. It’s easier for the reader to digest one instruction at a time.

Give directions in no uncertain terms like so:
“Next, you’ll read the sensor…”
“Make a variable called thisPin…”

Avoid phrases that add no information. Don’t tell the reader that “You want to set the pins”, just tell her “Set the pins.”

Use pictures and schematics rather than just schematics alone. Many electronics hobbyists don’t read schematics.

Check your assumptions. Does the reader understand all the concepts you’ve used in your tutorial? If not, explain them or link to another tutorial that does.

Explain things conceptually, so the reader has a big picture of what he’s going to do. Then lay out instructions on how to use it step-by-step.

Whenever you use a technical term for the first time, define it. Have someone else check that you defined all new terms. There are probably one or two that you missed.

Be consistent with the terms you use. If you refer to a component or concept by a new name, make the relationship to the other name explicit. Don’t use two terms interchangeably unless you tell the reader that they are interchangeable.

Don’t use acronyms or abbreviations without spelling them out first.

Make your example do one thing well. Don’t combine concepts or functions unless it’s a tutorial about combining concepts.




Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: