Semaphore is excited about building a collection of technical articles to help software developers expand their knowledge and advance their craft. The goal is to build a collection of high quality materials covering all practices and tools related to continuous delivery.
For this reason, the Semaphore community is open for contributions and the goal of this article is to provide some style guidelines for writing new tutorials.
When writing for the Semaphore community, you should always have in mind the person reading your article. Some general guidelines:
- Spell out every step you are taking as clearly as possible. Assumption is the mother of all problems, especially when it’s about the reader’s background knowledge in this case.
- Write in a way that any smart person will understand.
- Be sure to try out all the steps taken in your tutorial yourself, in the environment you instructed the reader to set up.
- Always be asking yourself if you are communicating clearly. Prefer shorter sentences and paragraphs. Unfold your ideas gradually.
Semaphore tutorials should be as focused and self-contained as possible. After completing a tutorial, the reader should have either:
- Thoroughly learned about a new topic or how to use a tool, e.g. what is continuous integration, or how to test Node.js services using Mocha.
- Done something from start to finish, e.g. deployed a simple Clojure application to OpenShift.
Your writing should either thoroughly cover a topic in one or a series of articles, or reference any prerequisites explained in a previously published Semaphore tutorial. If such an article does not yet exist, you should write that one first. We will happily discuss this with you during the author submission process.
For example, if you would like to write about writing a custom RSpec matcher, there is no need to explain what TDD and BDD are and include a general introduction to RSpec and the installation procedure. Instead, link to the existing Semaphore tutorials explaining those things.
If a prerequisite is short and simple enough, do spell it out in your article, e.g. how to configure a library or install a package. Do not ask the reader to go to an external site to complete a task.
Person and Tone
The goal of every Semaphore tutorial is to educate the reader, which makes writing them different from blogging. Whereas blog posts usually involve personal opinions, experiences and even feelings, Semaphore tutorials are written in a friendly, but formal tone.
All articles should be limited to the first person plural (we, our) and second person (you, your). Here’s an example:
Our first test will check if the homepage really displays “Hello World” message. Since we’re testing by opening a real browser, the test needs some setup and teardown. […] You now have the basic setup for testing web applications with Selenium.
Avoid adjectives that echo subjectivity, unnecessary comments or humor. For example, instead of “Thanks to the awesome XY community, there are many plugins”, you could write “The XY community has created many plugins”.
On the other hand, do use analogies or metaphors that help the reader understand a process or ideas of the subject at hand.
Images and Diagrams
The use of images and diagrams is encouraged whenever they help the reader understand the subject better. This could be by summarizing an important idea, explaining a process, or documenting the expected current state with a screenshot.
Refer to the formatting guide for information on how to format the images.
If you would like your article to include a diagram, send us a sketch, and we will produce the final image.
Semaphore editors may also decide to attach an illustration to some of the published tutorials, for visual appeal.
If your tutorial involves showing code, then choosing what your code will be about is important, and sometimes even challenging. Some things to avoid include:
barand similar generic names.
- Having a disbalance between the complexity of the tool or idea and the code examples. Reading such tutorials almost never helps the reader learn a new skill effectively.
Introductory tutorials should strive to cover a complete, self-contained project from start to finish. For example, a devops cookbook which installs and configures a database server, or developing and testing a simplified Todo application.
On the other hand, code snippets in tutorials covering more advanced topics should be extensive, but do not need to form a fully functional project. For example, if your tutorial is about refactoring a Rails web application controller with tests, you should start with code which really is worth refactoring, i.e., sufficiently close to what appears in reality.
Do not write articles which discuss a development methodology or tool without showing example code.
Always spell out what each code snippet does and explain in detail any new concepts it introduces, or link to an existing Semaphore article to avoid long explanations or repetition.
If you are writing a procedural tutorial which the reader is expected to follow on their own computer, always mention the file where the code snippet belongs. You can include it either in the text or in a comment as the first line of the snippet.
We encourage you to browse through the existing articles to get an idea of what your article should look like. When in doubt, ask your person of contact at Semaphore for an opinion. Happy writing!