Review page - Real world identifiers

[kathryn-ods]

Review of https://standard.openownership.org/en/latest/schema/guidance/identifiers.html

• remove information that is not relevant to this section/repeated elsewhere
• edit in line with style guide

[kd-ods]

@kathryn-ods - I went to review the PR #531, and I've realised that ideally we need to review the content of this Real World Identifiers docs page, alongside the description fields of the Identifier object (and the intro text on the reference.rst docs page).

And there's this feedback from tiredpixel to consider as we do this work.

We should consider whether a primary aim with editing a page like this is to bring into the schema (and onto the reference page) as much normative content as possible. If that's a principle we should follow, then we should note it in the handbook too.

I realise that all that potentially widens the scope of this ticket. What do you think?

[kathryn-ods]

Yes agreed there's some bigger picture things to consider here around identifiers.

We should consider whether a primary aim with editing a page like this is to bring into the schema (and onto the reference page) as much normative content as possible. If that's a principle we should follow, then we should note it in the handbook too.

I am generally in favour of doing this. On the current page there's a breakdown of the different fields in the identifier object - I think this sort of content should be reserved for the reference page. The style guide does say we should avoid repeating information, we could also add more specific guidance on where types of information should go.

[kathryn-ods]

@kd-ods I've closed #531 as this page needs more discussion before merging. Here's the google doc showing my edits with some thoughts - have a look when you get a chance. https://docs.google.com/document/d/1IDMZKXrrPMSwRk5eNTxYyeJeUaCUbahcnTEkbKQkugo/edit?usp=sharing

[kathryn-ods]

@kd-ods now that the schema descriptions have been reviewed now might be a good time to come back to this. I'm a bit concerned parts of this page are repeating/contradicting what the guidance says.

[kd-ods]

@kathryn-ods - Once I started making suggested edits and saw your comments, I realised this page needs a wholesale re-write, putting in some thought to what we usefully want to say beyond what's in the schema.

OK if I take a crack at that Thurs?

[kathryn-ods]

@kd-ods ok with me!

[kd-ods]

@kathryn-ods - this docs page is ready for you to take a look at now: https://docs.google.com/document/d/1IDMZKXrrPMSwRk5eNTxYyeJeUaCUbahcnTEkbKQkugo/edit?pli=1

(It's not a revolutionary re-write because I still think it's useful to have a page which summarises all the places in the schema where interoperability is supported by allowing inclusion of 3rd party identifiers.)

[StephenAbbott]

@kd-ods @kathryn-ods Is there a good place in updated version to link to the reliable identifiers guidance? https://www.openownership.org/en/publications/using-reliable-identifiers-for-corporate-vehicles-in-beneficial-ownership-data/