Document blog post review process

It's become apparent over the last weeks that we don't really have a well defined process for blog posts, who reviews them, how, and what the requirements for merging are.

For edge posts, it is agreed that they can go in with zero reviews (push directly to master), although a review is also fine (depending on the issue and who is writing the post). This is fine.

I discussed a bit with Ollie today, and for the main site we want to propose some kind of process to help us get things done more efficiently.

For a new blog post, the author should open the MR as a draft and request reviews from folks who should be involved in authorship (e.g. for the systemd blog post this would be me and maybe Clayton and Ollie). This shouldn't be a fixed list and it can be changed - if you think it's important that you provide feedback to a blog post then you should assign yourself as a reviewer.

At this stage, the blog post structure and contents might change a lot, as was the case for !261 (merged) for example. We should avoid leaving reviews to address spelling, grammar, and punctuation (SPAG) at this point as it might become irrelevant on the next iteration.

Once there is general agreement over the structure and content, the post should be unmarked as draft. At this point SPAG reviews are acceptable.

The blog post is ready to merge once the requested reviewers have approved it, it will then go through Ollie who will do a final check before merging the post and making a mastodon announcement.

---

In general, we should aim to avoid having too many folks reviewing a blog post, it can quickly spiral and result in a lot of additional effort by the author. It is also generally not useful to get approvals on a post by someone who hasn't previously left feedback (unless that person is marked as a reviewer -- in which case their approval is explicitly requested).

Regarding SPAG reviews, we could use GitLab approval rules to dictate that some folks take on the role of checking for these things, in which case an approval from them will show up as an approval for SPAG specifically.

---

Let's discuss this proposal, and aim to come up with a version we can document on the wiki.

Regarding SPAG reviews, we could use GitLab approval rules to dictate that some folks take on the role of checking for these things, in which case an approval from them will show up as an approval for SPAG specifically.

I've been thinking about this and I think one thing that's become obvious is that I find this more important and interesting than many others on the team, which is understandable. I like polishing language use, removing ambiguities, improving brevity and such, but it seems like others think these aren't worthwhile pursuits unless they're typos or other blatant errors.

This isn't something I necessarily disagree with, but it is something I find fun and rewarding to do. However, it doesn't make sense to involve others in this if they don't care about it. So, I'm wondering if it would be make sense to have the SPAG review part separate without the original author's involvement, unless they want to involve themselves with it.

However, I'm not a native English speaker and I don't have any formal English qualifications, so just because I prefer something doesn't necessarily mean it's better. As such, it would be ideal if someone else could at least help with reviewing my proposed changes. @susurrus did mention in our maintainer room has he also likes "SPAGhetti" and that he would be happy to help with it, so maybe us two could handle this "stage" together if the original author doesn't care for it — assuming Bryant thinks this particular scheme is a good idea, I haven't asked.

By Newbyte on 2024-05-20T11:46:57

Regarding my experience as a blog post author, I find SPAG useful, but can be very hard to incorporate the improvements. I would suggest that a way to "separate the review from the original author" is to allow people doing these reviews to force-push. I find it great when somebody else fixes some wording or a stray comma. Though it can be frustrating if I have to fix 7 of those myself.

By Pablo Correa Gomez on 2024-05-21T14:42:33

I think having a SPAG pass by someone would be good. As Newbyte mentioned, I'm happy to be a SPAG reviewer. And if we force-push the changes, it seems low-effort for the authors. The reason I haven't done that until now, is I didn't want to upset anyone by changing what they wrote. But if everyone agrees to this approach, then that's settled.

If authors do want to get better at writing, then them being involved with the feedback would be useful. I don't believe everyone does, however, but maybe the author could flag Newbyte and me in and tell us if they want the feedback or for us to just polish it.

A last point about feedback, is that if people improve their initial drafts, it makes it easier for us. However, I don't think we have enough blogposts that we have a bandwidth problem here, so I think being biased towards no feedback, just silently polishing things, still makes sense.

By Bryant Mairs on 2024-05-20T17:48:24

SPAG is super important and I definitely appreciate folks who like to dive into the SPAGhetti, but IMHO it should done towards the end of the review process and not sooner. The reason for this is that sometimes big parts of a document's structure/content need to change, and doing SPAG passes on it before that has been settled can make it harder for contributors trying to sort out what still needs to be addressed wrt any bigger structure/content changes that might be requested. Early SPAG feedback might not be applicable in later revs, and you'd probably want to do another SPAG review at the end anyways to go over any new changes.

By clayton craft on 2024-05-21T21:57:16

mentioned in merge request !267 (merged)

By Newbyte on 2024-05-20T10:13:29

Some more food for thought: https://danluu.com/corp-eng-blogs/

By Bryant Mairs on 2024-06-01T10:29:25

When are we doing SPAG for !271 (merged), given that this isn't finalised yet?

By Newbyte on 2024-06-16T16:39:44

feel free to do now :)

By Oliver Smith on 2024-06-16T16:39:44

(or in a few minutes, changing a few details)

By Oliver Smith on 2024-06-16T16:40:05

added discussion label