[FEAT] Style guide for Splink documentation

[samnlindsay]

Is your proposal related to a problem?

As the documentation is rapidly developing by multiple contributors, it's easy for similar content to be presented slightly differently and inconsistently. This makes the docs more challenging to read, albeit likely to go unnoticed by most users.

Describe the solution you'd like

Agreeing on a simple style guide that all contributors can follow. For example:

• Acronyms
• Consistent terminology (e.g. record linkage vs entity resolution vs data linking)
• Formatting (e.g. Match Weight or match weight)

Describe alternatives you've considered

Maintaining the status quo

Additional context

GDS A-to-Z style guide

Article on technical writing style guides

[RossKen]

Yea, totally agree on this. I think if we decide on some of these principles we can add a glossary of commonly used terms as well.

[RossKen]

@hrahim-moj not sure you have any thoughts/ideas on how to best apply style guides across technical docs? Are there any tools that can help automate this?

[hrahim-moj]

A glossary is a great shout. I'd otherwise follow the GDS style guide and their general guidance where possible; I've collated a list on our Confluence space.

Do you review new content before it is published? That also helps keep things consistent/avoid duplication.

[RossKen]

A glossary is a great shout. I'd otherwise follow the GDS style guide and their general guidance where possible; I've collated a list on our Confluence space.

Do you review new content before it is published? That also helps keep things consistent/avoid duplication.

Thanks for the links @hrahim-moj

Yea, we do a review, but we do not really have any clear, agreed-upon style (and none of us have memorised the GDS style guide) so just trying to think of ways to flag things up in an automated way to make reviewing easier.