Repo documentation guidance

[SHession]

What is being recommended?

This document provides guidance and a template for writing effective documentation for our repos. It is intended to improve the general quality of these documents, providing actionable advice, as well as a template to use.

What's the context?

I've noticed during the tools audit that knowledge of some tools is becoming increasingly sparse. The aim is to make discovering and understanding tools much simpler.

Note

The recommendations in this repository are intended to share engineering best practices for all of Product & Engineering (P&E) in the open.

Some considerations:

• Should this really be an ADR in another repository?
• Have you sought review widely enough (Developer Experience, Heads of Engineering)?
• If it is security related, should you consult with Information Security?

[tjsilver]

What does this comment do?

[SHession]

One of the CI checks was flagging the paragraph for inclusive language, but the context here is fine.

[NovemberTang]

Is it worth saying that it can be useful to readers if the documentation includes things like intended audience and knowledge prerequisites?

[SHession]

Thanks @NovemberTang, I have added an extra couple of sentences to encourage this. Let me know if you that that covers it 🙏

[NovemberTang]

Thank you @SHession , this is great! I've left a couple of small QOL comments, but nothing blocking 🥇

[joelochlann]

Re: our discussion of advice on how to structure docs for LLMs

I think the general guidance should be that things that are useful for humans are also useful for LLMs, and in particular avoiding redundancy between docs/comments and code: docs should provide complementary information, not duplicate information.

Examples of complementary information:

• Why this approach as opposed to obvious alternatives? A key bit information that is present when the code is created that often disappears after is: what we were the alternative solutions that were ruled out, and why were they ruled out?

A couple of specific things I've thought of, which we often do anyway, but not always:

• Markdown is the bread-and-butter of LLMs because it is token-efficient (no need for open/close tags) while allowing hierarchical structure. Also it looks great in GitHub. Always use markdown!
• Prefer markdown README in the repo to a separate wiki
• Where it makes sense, co-locate markdown docs with relevant code, e.g. README.md files in the root of folders
• In the top-level README, provide a table of contents that helps humans and LLMs understand the high-level structure of the repo, and to find all the relevant docs. So, link to any folders that contain exclusively documentation, and describe the pattern that would help someone easily find docs that are scattered around, for instance: "all docs are either README.md in an arbitrary folder, or .md files within docs/"
• [not strictly docs but should be in our recommendations] Create a .github/copilot-instructions.md. Here's one example in the Guardian estate: https://github.com/guardian/support-service-lambdas/blob/main/.github/copilot-instructions.md

Another thing which we want to recommend people start exploring: https://github.com/anthropics/skills

[emdash-ie]

As far as I can tell, this section doesn’t explain anywhere why writing for a specific audience is valuable. I think a good structure for the section might be to start with that explanation, before giving examples of possible audiences to consider and advice to help identify a good intended audience.

[SHession]

Great point, that is a notable omission. I will add something in.

[SHession]

I've added some detail to this section, I would value your thoughts.

[emdash-ie]

I love it, thanks!

[emdash-ie]

Does this strike you as true? It doesn’t apply to me (I would probably prefer the paragraphs in many cases), but I’m uncertain what’s typical.

[SHession]

Good point, this was also taken from the technical writing course, but it is very much subjective. Although, I think the point stands that many people find tables useful.

I'm open to alternatives quotes or phrasing.

[emdash-ie]

I think the reason I dislike this piece of text is that it implies engineers are all the same – engineers prefer tables, engineers have analytic minds. As I don’t prefer tables, I think it (slightly!) implies I’m not a real engineer.

That’s probably not that important, but I also don’t think the paragraph is adding much to this section: we’ve already recommended tables in the first paragraph, so this strikes me as just a bit of unnecessary colour. If we’re drawing attention to some extra markdown features here, I’d be more tempted to highlight alerts or GitHub’s support for mermaid diagrams.

[SHession]

I agree with this. I have removed the unhelpful quote and replaced it with a reference to the mermaid docs.

[davidfurey]

When I first read this I missed the key bit "recently learned".

I presume we aren't suggesting expanding USB, CRC, HTTPS, etc.

[emdash-ie]

Same here actually – clicking through to the source makes it clearer that common acronyms should still be used.

[SHession]

Thanks for your help on this, @joelochlann. I have attempted to distil your comment into this section. I would value any thoughts or suggestions you may have 🙏