Keeping todos, incomplete drafts, and future work

Sometimes it's not possible to do something as it should be done. This could be because there's a blocking bug, because you haven't figured something out yet, or simply because you ran out of time.

It's often tempting to leave a note within the paragraph text like

TODO finish this section

or

TODO update this once 15.3 is released

In general, you should avoid including this within your draft article wherever possible. These are the most common things that 'slip through' our pipeline and find there way into the live versions of the articles when this was not intended.

Rather keep a note somewhere else like GitHub, Slack, Trello, a physical notebook, or whatever makes sense in your workflow. Yes, it's harder to also now have to keep a link between the note and the article, but it means we'll never publis the note by mistake.

During QA and editing

If you see any incomplete work or TODO statements in a draft, you should immediately query this with the author and not assume that someone else will catch this 'down the line' (everyone tends to think that someone else will catch it), as in the fairly famous and slightly cliched story:

This is a story about four people named Everybody, Somebody, Anybody and Nobody. There was an important job to be done and Everybody was sure that Somebody would do it. Anybody could have done it, but Nobody did it. Somebody got angry about that, because it was Everybody’s job. Everybody thought Anybody could do it, but Nobody realized that Everybody wouldn’t do it. It ended up that Everybody blamed Somebody when Nobody did what Anybody could have.