We're hiring new talents!

Contents

Tech­ni­cal Pub­li­ca­tion Guidelines

Enclaive is excit­ed to wel­come new authors to its open-source com­mu­ni­ty while con­tin­u­al­ly pro­vid­ing valu­able con­tent for every­one. To ensure, how­ev­er, that the arti­cles have con­sis­tent qual­i­ty and style, we would like every author to fol­low our tech­ni­cal writ­ing guide­lines stat­ed below. 

To get pub­lished quick­ly, we rec­om­mend that you fol­low the Style and Struc­ture sec­tions before you begin work­ing on your arti­cle. You can also use the For­mat­ting sec­tion as a ref­er­ence while writ­ing your article.

Style

We would like to ensure that all Enclaive arti­cles are:

  • clear, detailed and writ­ten for all expe­ri­ence leveles
  • tech­ni­cal­ly com­pre­hen­sive and correct
  • use­ful and self-contained
Writ­ten for all expe­ri­ence levels

Our arti­cles are writ­ten to be as clear and detailed as pos­si­ble, mak­ing sure that all read­er’s knowl­edge lev­els under­stand the tutorial. 

We expect our arti­cles to be detailed enough, mean­ing they should include every com­mand a read­er needs to go from their first start­ing point to the final, work­ing set­up. Read­ers should also get all the expla­na­tions and back­ground infor­ma­tion they need to under­stand the tuto­r­i­al. The goal is for our read­ers to learn the con­cepts, not just copy and paste code and commands.

We encour­age our read­ers to work through the arti­cle, under­stand the con­cept and get to the suc­cess­ful, work­ing set­up. Our aim is that read­ers can grow as devel­op­ers and expand their knowl­edge by using the tuto­r­i­al sec­tion on our com­mu­ni­ty page.

Tech­ni­cal­ly com­pre­hen­sive and correct

Our tuto­ri­als need to be tech­ni­cal­ly detailed and fol­low indus­try stan­dards. Our read­ers should be able to under­stand and apply the prin­ci­ples learned in the arti­cle. This means the author has to cov­er the top­ic in the arti­cle comprehensively. 

The author needs to pro­vide the read­ers with the back­ground infor­ma­tion, for them to grow their knowl­edge and devel­op the skill to under­stand and make the set­up changes them­selves. They should learn the con­cepts, not just copy and paste the code provided.

Before sub­mit­ting the arti­cle, the author has to test his code and ensure the steps work exact­ly as described. Our edi­tor team will also test the com­mands pro­vid­ed in each sub­mit­ted arti­cle to ensure accu­ra­cy and iden­ti­fy miss­ing steps. Each step has to be explained in detail, so every read­er regard­less of his back­ground can work his way through the tuto­r­i­al to the final, work­ing setup.

Use­ful and self-contained

Each tuto­r­i­al should pro­vide the read­ers with use­ful infor­ma­tion on a spe­cif­ic top­ic: after fin­ish­ing the arti­cle, the read­er should be able to install, set up, or con­fig­ure some­thing. The arti­cle should there­fore have a prac­ti­cal approach, pro­vid­ing knowl­edge to the com­mu­ni­ty and mak­ing it usable for future setups. This means that the author has to ensure that the top­ic is cov­ered thor­ough­ly in the tutorial. 

If a link to pub­lished arti­cles on our com­mu­ni­ty page is need­ed for addi­tion­al infor­ma­tion, the author has to pro­vide this mark with this infor­ma­tion in the tuto­r­i­al accord­ing­ly. If there is no arti­cle on the com­mu­ni­ty page, the author should try to sum­ma­rize this in a short para­graph in the exist­ing arti­cle. Only if this is not pos­si­ble or would make the entire arti­cle unclear, the author should link the read­ers to an off­site page that pro­vides this addi­tion­al information.

Struc­ture

All Enclaive arti­cles have a con­sis­tent struc­ture, which includes an intro­duc­tion, a con­clu­sion, and ‑upfront- any pre­req­ui­sites nec­es­sary for a read­er to get start­ed. Here are some spe­cif­ic struc­ture tem­plates depend­ing on the type of arti­cle the author wants to submit.

Pro­ce­dur­al tuto­ri­als walk the read­er through accom­plish­ing a com­plex task. The fol­low­ing struc­ture would be used in this case:

  • Title (Lev­el 1 heading)
  • Intro­duc­tion (Lev­el 3 heading)
  • Goals (Option­al)
  • Pre­req­ui­sites (Lev­el 2 heading)
  • Step 1 — Doing the First Thing (Lev­el 2 heading)
  • Step 2 — Doing the Next Thing (Lev­el 2 heading)
  • Step n — Doing the Last Thing (Lev­el 2 heading)
  • Con­clu­sion (Lev­el 2 heading)

Con­cep­tu­al arti­cles on the oth­er hand look sim­i­lar to the pro­ce­dur­al arti­cles but might not always have a pre­req­ui­sites sec­tion, a Goals sec­tion, and might not fol­low the “Step” structure:

  • Title (Lev­el 1 heading)
  • Intro­duc­tion (Lev­el 3 heading)
  • Pre­req­ui­sites (option­al) (Lev­el 2 heading)
  • Doing the First Thing (Lev­el 2 heading)
  • Doing the Next Thing (Lev­el 2 heading)
  • Doing the Last Thing (Lev­el 2 heading)
  • Con­clu­sion (Lev­el 2 heading)

For oth­er small arti­cles, focused on a very small spe­cif­ic task/solution, the struc­ture would look like this:

  • Title (Lev­el 1 heading)
  • Intro­duc­tion
  • Pre­req­ui­sites (option­al) (Lev­el 2 heading)
  • Arti­cle body
  • Con­clu­sion

Videos are also a great way to share your knowl­edge with the com­mu­ni­ty. If you are inter­est­ed in cre­at­ing a video, please make sure you also fol­low a con­sis­tent struc­ture (intro­duc­tion, pre­req­ui­sites, body, conclusion). 

For­mat­ting

An arti­cle must be orga­nized prop­er­ly to draw the atten­tion of the read­ers. When post­ing an arti­cle on Enclaives Com­mu­ni­ty page, we want you to focus on your arti­cle’s con­tent, not on fan­cy HTML tricks. The lay­out should be sim­ple and clean, mak­ing it easy for your read­ers to con­sume your work.

With this in mind, we’ve put togeth­er some sim­ple rules to help make your life a lit­tle easier.

The Rules
  1. Stick to HTML con­ven­tions and use HTML tags as per com­mon use.

For instance, use tags to denote para­graphs. Please don’t use BR tags to break paragraphs.

  1. Use sim­ple and clean HTML only.

By this, we mean: stick to a sim­ple and clean HTML. Use or STRONG to make text bold, use CODE tags to out­line inline code, and PRE to wrap code blocks. Don’t wrap every­thing in SPAN blocks with crazy styles: our edi­tor team will have to change every­thing after submission.

  1. Keep code­blocks as small as possible

Make sure you don’t send unnec­es­sary long code blocks. Read­ers should be able to eas­i­ly con­sume your tuto­ri­als. Delete all the parts that aren’t direct­ly rel­e­vant to the explanation. 

Wrap up

Now that you have read our tech­ni­cal writ­ing guide­lines, make sure you join our Enclaive com­mu­ni­ty and become an author by shar­ing your knowl­edge with us.

Facebook
Twitter
LinkedIn
WhatsApp
XING

Contact sales

Cookie Consent with Real Cookie Banner