Skip to content

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.

Writing a draft

As a writer, you'll receive a brief with requirements and an overall goal for an article. Sometimes we'll have very specific requirements, sometimes you'll need to make more choices about an interesting example or use case.

Different writers have different strategies for building and writing. Some people prefer to completely finish the 'build' step before starting the 'write' step, while others prefer to do them both in parallel. Either way, you'll likely need to spend time revising both code/configuration samples and the draft article before submitting it for editing and QA.

Once you submit a draft, you should be very confident that it is

  • Correct - you're not making any wrong or misleading claims and your code samples work
  • Interesting and valuable - a reader is likely to get what they need from reading it
  • Clear and precise - a reader won't have any issues following along
  • Well presented - formatting, screenshots and layout all work and look good

Although your draft will go through a QA and Editing process, they are there to raise our quality bar and to find things that you wouldn't have been able to find on your own.

In the case that either QA or Editing feels like your draft does not meet our bar, they will return it to you with a note. This should never happen, and if it does we'll have a discussion about why and how to prevent it in future.

Reasons QA or Editing might reject an article

  • It doesn't work - the basic instructions don't lead to the claimed result
  • It's badly structured or unclear and looks more like a rough draft than a final Ritza article
  • It has obvious typos or grammatical errors that tools like Grammarly or LLMs can easily catch
  • It contains mistakes that they've pointed out in previous articles and asked you to keep in mind for future

For minor issues or understandable oversights like code not being fully compatible with different systems, QA or editing will fix these and keep the article moving forwards. Articles going 'backwards' in our pipeline disrupts everyone's schedules and plans, and leads to delays in us delivering work, so only in exceptional cases should work ever go backwards in our pipeline.

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.

For online services, the writer should also create a new accout or trial account if feasible, or a new project within an online account if its paid. You can create as many email addresses as you need by adding + suffixes to your ritza.co account like bob+trial2@paidservce.com. Gmail will ignore everything from the + to the @ so any emails sent to that address will still land in your normal inbox.

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