How to write and submit your draft

Each article is unique and might not fit perfectly into this pattern. However most articles we write have some technical ("build") component and some writing ("write") component. Often the effort to create a draft is split 50-50 between building and writing, though for very technical guides, there might be more effort on the building side and for higher level more thought-leadership style posts, it is often the other way around.

Build

Build is a generic way of how we think about writing code, configuring and setting up integrations or other systems, and generally getting to some outcome that the reader of the article wants to replicate.

A common pattern we follow is

• I built this thing
• Here's a step-by-step guide showing how you can build the same thing
• Or here is the completed application (with a link to a GitHub repository) if you want to skip the building part and just have it

While it's often a good strategy to build everything first and then write about it, it can be hard to remember exactly what you did. Also often during the writing phase you'll be tempted to add or fix some smaller aspects, so often a good flow is to combine the build and write step (keeping a rough set of steps, commands, screenshots and notes), and then do another run through to complete the draft.

Write

This is the bit that people often enjoy less than the building, so it's important to timebox the building part. Some writers find that getting started from a blank page it the hardest part, so a good strategy is to set a goal to just write one or two sentences, and see if that helps get things moving.

Either way, the writer works through the build steps again, making sure each one works as expected, and writes down how to do it. At the same time they try to anticiapte where the reader might get lost or confused, and pre-empt any questions. The best articles will always catch the reader at drop off points, like "if you see this error, then..." or "if you don't understand this concept, then...".

Pre-QA check

Before submitting the article to QA, the writer should do a clean run through of the article, and follow the steps as if they were a reader. This usually means deleting the entire project and wiping all dependencies, virtual environments, docker containers and similar 'state' that they have left on their machine from building, and starting over.

Remember that your goal is to have QA run through your article and pass it onto editing without needing any changes.