Skip to content

Our publishing pipeline

This is how we produce technical content.

Roles

  • Producer - talks to the customer, figures out requirements, and writes a brief
  • Engineering Writer - an engineer who builds a proof-of-concept project and writes an article about it
  • QA Engineer - a second engineer who follows the article as a reader would and checks for technical accuracy, code quality, and screenshot quality
  • Editor - a language expert improves the flow, fixes any language errors, and gives feedback to the writer, working with the writer on revisions to the text if necessary.

Pipeline

Each article goes through several stages, some of them optional. An overview of the article pipeline is below.

Ritza publishing pipeline

  • Brief: The Producer creates a brief explaining the goal of the article and defining any other requirements.
  • Draft: The Engineering Writer creates a POC if required, and writes a draft. At the end they do a full readthrough and runthrough of the article, as a reader would, and fix any issues before submitting it to QA.
  • QA: The QA Engineer reads the article through the eyes of a reader, running all examples, ensuring that it renders correctly, updating screenshots with higher quality versions. Smaller issues are fixed by QA. Bigger issues are returned to the writer to address.
  • Edit: The Editor reads through the draft and fixes any grammatical or consistency issues. If necessary, they check edits with the writer, and discuss overall strucure with the writer.
  • Writer-review: The writer checks the changes made by the editor, and discusses any changes that they disagree on.
  • Deliver: The Producer shares the work with the customer.
  • Revise: If the customer wants changes, the Producer decides how many stages back in the pipeline to go. For a rewrite or bigger changes, the article goes back to the writer. For smaller technical changes, it goes back to QA. For language changes, it goes back to editing. Whichever stage revisions start on, the article goes again through all subsequent stages.
  • Publish: Either the customer or the Producer publishes the article.

Overview of git branches and PR title naming conventions

Here's an overview of our core git process for producing an article. It might have variations depending on project specifics, but all else being equal this is generally what should happen.

Naming conventions

  • Draft branch name draft-how-to-foo-with-bar, PR title draft: How to Foo with Bar
  • QA branch name qa-how-to-foo-with-bar, PR title qa: How to Foo with Bar
  • Editing branch name edit-how-to-foo-with-bar, PR title edit: How to Foo with Bar
  • Revisions branch name revise-how-to-foo-with-bar, PR title revise: How to Foo with Bar

Merge order

Normally

  • Writer will open Draft PR
  • QA will open and merge QA PR into Draft
  • Editor will open and merge Edit PR into Draft
  • Editor will share the draft branch with ritza-deliver tag, and ask writer to confirm all changes (QA and Edit) are OK.