Enclaive is excited to welcome new authors to its open-source community while continually providing valuable content for everyone. To ensure, however, that the articles have consistent quality and style, we would like every author to follow our technical writing guidelines stated below.
To get published quickly, we recommend that you follow the Style and Structure sections before you begin working on your article. You can also use the Formatting section as a reference while writing your article.
Style
We would like to ensure that all Enclaive articles are:
- clear, detailed and written for all experience leveles
- technically comprehensive and correct
- useful and self-contained
Written for all experience levels
Our articles are written to be as clear and detailed as possible, making sure that all reader’s knowledge levels understand the tutorial.
We expect our articles to be detailed enough, meaning they should include every command a reader needs to go from their first starting point to the final, working setup. Readers should also get all the explanations and background information they need to understand the tutorial. The goal is for our readers to learn the concepts, not just copy and paste code and commands.
We encourage our readers to work through the article, understand the concept and get to the successful, working setup. Our aim is that readers can grow as developers and expand their knowledge by using the tutorial section on our community page.
Technically comprehensive and correct
Our tutorials need to be technically detailed and follow industry standards. Our readers should be able to understand and apply the principles learned in the article. This means the author has to cover the topic in the article comprehensively.
The author needs to provide the readers with the background information, for them to grow their knowledge and develop the skill to understand and make the setup changes themselves. They should learn the concepts, not just copy and paste the code provided.
Before submitting the article, the author has to test his code and ensure the steps work exactly as described. Our editor team will also test the commands provided in each submitted article to ensure accuracy and identify missing steps. Each step has to be explained in detail, so every reader regardless of his background can work his way through the tutorial to the final, working setup.
Useful and self-contained
Each tutorial should provide the readers with useful information on a specific topic: after finishing the article, the reader should be able to install, set up, or configure something. The article should therefore have a practical approach, providing knowledge to the community and making it usable for future setups. This means that the author has to ensure that the topic is covered thoroughly in the tutorial.
If a link to published articles on our community page is needed for additional information, the author has to provide this mark with this information in the tutorial accordingly. If there is no article on the community page, the author should try to summarize this in a short paragraph in the existing article. Only if this is not possible or would make the entire article unclear, the author should link the readers to an offsite page that provides this additional information.
Structure
All Enclaive articles have a consistent structure, which includes an introduction, a conclusion, and ‑upfront- any prerequisites necessary for a reader to get started. Here are some specific structure templates depending on the type of article the author wants to submit.
Procedural tutorials walk the reader through accomplishing a complex task. The following structure would be used in this case:
- Title (Level 1 heading)
- Introduction (Level 3 heading)
- Goals (Optional)
- Prerequisites (Level 2 heading)
- Step 1 — Doing the First Thing (Level 2 heading)
- Step 2 — Doing the Next Thing (Level 2 heading)
- …
- Step n — Doing the Last Thing (Level 2 heading)
- Conclusion (Level 2 heading)
Conceptual articles on the other hand look similar to the procedural articles but might not always have a prerequisites section, a Goals section, and might not follow the “Step” structure:
- Title (Level 1 heading)
- Introduction (Level 3 heading)
- Prerequisites (optional) (Level 2 heading)
- Doing the First Thing (Level 2 heading)
- Doing the Next Thing (Level 2 heading)
- …
- Doing the Last Thing (Level 2 heading)
- Conclusion (Level 2 heading)
For other small articles, focused on a very small specific task/solution, the structure would look like this:
- Title (Level 1 heading)
- Introduction
- Prerequisites (optional) (Level 2 heading)
- Article body
- Conclusion
Videos are also a great way to share your knowledge with the community. If you are interested in creating a video, please make sure you also follow a consistent structure (introduction, prerequisites, body, conclusion).
Formatting
An article must be organized properly to draw the attention of the readers. When posting an article on Enclaives Community page, we want you to focus on your article’s content, not on fancy HTML tricks. The layout should be simple and clean, making it easy for your readers to consume your work.
With this in mind, we’ve put together some simple rules to help make your life a little easier.
The Rules
- Stick to HTML conventions and use HTML tags as per common use.
For instance, use P tags to denote paragraphs. Please don’t use BR tags to break paragraphs.
- Use simple and clean HTML only.
By this, we mean: stick to a simple and clean HTML. Use B or STRONG to make text bold, use CODE tags to outline inline code, and PRE to wrap code blocks. Don’t wrap everything in SPAN blocks with crazy styles: our editor team will have to change everything after submission.
- Keep codeblocks as small as possible
Make sure you don’t send unnecessary long code blocks. Readers should be able to easily consume your tutorials. Delete all the parts that aren’t directly relevant to the explanation.
Wrap up
Now that you have read our technical writing guidelines, make sure you join our Enclaive community and become an author by sharing your knowledge with us.
