Define what the practices are trying to achieve

[nottrobin]

I'm super happy with how the amount of content in this practices repo has exploded recently. It's all a great effort. While we were building up content in this repo, I took the attitude that basically the more content the better.

However (as @bartaz helped me realise), we're now at a place where we have a bunch of different sorts of things in practices:

1. policies - browser support
2. explicit rules - foosball
3. statements about our coding standards - python, javascript, copy-reviews (this should be reformatted)
4. recommendations about how we should work - QA steps, project philosophy
5. project lists - ports
6. documentation - the run script
7. guides/articles/tutorials - stylesheets, github, zenhub

Now that I feel the practices are reaching some level of maturity, it might be time to be explicit about what sort of content we expect them to contain. We could create the statement first, as a practice, and then start updating or moving the content to fit in with the practice.

So, personally I feel that the practices should contain statements about how we should work (the whole spectrum from hard "you must" statements to softer "you should" through to "you may want to think about"), but within that, to try to be concise and to the point. We should write the minimum needed to convey our position on a particular topic.

This means that, for me, anything that feels like a "how to" guide, or a tutorial should live outside the practices, but potentially be linked to from within the practices. If the content already exists out on the wider web, we should simply link to it there (no point duplicating - e.g. BEM). If not, I propose that we keep such guides in this project's wiki, or, even better, turn them into our own blog posts.

This would both help keep these practices more succinct and to the point, it would also mean that publishing such guides, which are only the author's attempt to help someone out, would be much lighter weight. We don't need the practices PR approval process for how-to guides.

I also think the "ports" document effectively falls into this category. The fact that we have created an unspoken exception for additions to this document to be merged right away with 1 approval is clearly a bit of a smell.

So I'd suggest that points 1-4 above are legitimate content for the practices, and 5-7 are not.

Any thoughts?

[matthewpaulthomas]

Writing design specs, I gradually realised a dilemma: the shorter one is, the more it leaves unanswered, but the longer it is, the less likely people read it at all. This led me towards focusing specs on details (a) that implementors are likely to get wrong, and (b) where “wrong” is actually bad. For example:

2. explicit rules - foosball

Learning foosball rules is a social process during onboarding. Nobody, I hope, would ever say “hey, you can’t do that, we’re stopping the game until you read the rules on the Practices site”. Having the rules be spoken-only also eases changes over time, for example the Spinning and Lifting changes over the past two years. So it might have been fun to write, but it seems a bit dead weight.

Another principle, which may help in slimming the practices, is “document something in the noticeable place that’s nearest to the actual thing”. For example, imagine someone submitted a practice for what issue reports should contain. Would it be accepted here? No, because the GitHub issue template is much nearer and therefore more noticeable. Similarly,

6. documentation - the run script

seems like it could be a ./run script template (and README template) in a repo that’s forked by anyone starting a new site. There, it would be much more visible to the implementors, while still being accessible to people wanting to bring an existing site into sync.

I also think the "ports" document effectively falls into this category. The fact that we have created an unspoken exception for additions to this document to be merged right away with 1 approval is clearly a bit of a smell.

If it doesn’t live here, then where? One possibility is a column in the spreadsheet of Canonical sites.

[nottrobin]

the shorter one is, the more it leaves unanswered, but the longer it is, the less likely people read it at all

Yes I totally agree. My point here is that we should be focusing on short, to the point statements - punchy but with important implications. Not long detailed guides.

This led me towards focusing specs on details (a) that implementors are likely to get wrong, and (b) where “wrong” is actually bad.

I'm not sure I quite agree with this maxim exactly. The mission we're on here is a more abstract one than simply defining steps that people should take while doing work. At their best, these practices anchor our team's culture - like the GDS design principles. The important things to write down might be things we all feel strongly about - like "Do less" or "Assume positive intent", they might be valuable abstract guiding principles, but hard to say whether anyone is "getting them wrong".

I'd rather define maxims along the lines of: Avoid talking about examples of real work too specifically (although real work could, probably often should, be used as examples) and instead try to distil advice into general, succinct statements that can be applied broadly.

So it might have been fun to write, but it seems a bit dead weight.

I agree this might not the the most shining example of a good "practice", but it's certainly not where I'd start. Well, we can take a poll, but personally I think the fun outweighs the weight in this case, especially when there are many more egregious examples of non-practice practices.

I suppose I don't think it matters that the number of documents in the practices are all that small - each document being short and to the point is more important.

I also think the "ports" document effectively falls into this category. ...

If it doesn’t live here, then where?

I'm thinking this project's wiki, where it can be easily edited without a strict review process.