Add 'About this site' section to the homepage/index

[dan-odsc]

Update the homepage/index - http://docs.openreferral.org/en/documentation-review/index.html#site-contents

1. Specify the distinction between 'reference' and 'guidance' Annotation from Greg - https://hyp.is/wQk-xGFZEe6aCpfo2uVs2w/docs.openreferral.org/en/latest/

&

2. Add guidance on the use of annotations

Greg

Hi – ok yes i received the notifications.

So yes i think the text there is along the lines of what we need. Maybe also a screenshot, i think we used to have that too?

I just think we probably want it under the About page. Maybe there needs to be a subsection that says "About this site" with a section for reference <> guidance and a section for annotation?

Alternatively maybe we don't want the home page to get so cluttered. but I do think it would help to make clear how users can comment on the docs.

Dan

'We'll want a line on the homepage about how the user can use hypothes.is to make annotations. on the previous version there is an example of this in highlighted text that rob has left an annotation on; we'll want to do that again with maybe more of a signpost to draw attention to it.'

I've searched 'annotation' on all versions and the only thing I can find resembling what you describe is on the Get Involved section of all versions.

Add annotations to this documentation site using hypothes.is - hypothes.is is an annotation service that is embedded in this site. (See the buttons in the top-right of this page.) Just highlight any text, and then use the pop-up box to add your comments. You will need to sign-up for a free account with hypothes.is.

What did you have in mind as 'more of a signpost'? I don't see any annotation from Rob on any other versions but I've added this Do you want this on the home page as well as the get involved page? Dan

[greggish]

I think this probably belongs on the Home page on the docs site, in the About section? Maybe in a subheader under Specifications but maybe its own section About this documentation?

And I assume something along these lines would suffice:

The Reference section is comprised of the various layers of the Human

Service Data Specifications – the ['normative'] elements of the standard.

The Implementation Guidance section provides direction and support materials to aid implementers. These contents [are 'non-normative,' which means they] aren't formally part of the standards, but may be helpful to readers who are learning about the standards.

I still don't love the phrase 'non-normative' – do we have an alternative? But if we define it clearly on the home page, it's ok.

[mrshll1001]

In the short term we can create an 'About this site' heading on the landing page. I do think we should be thinking in terms of "what problem are we trying to solve" before we charge ahead, as that will allow us to develop a roadmap towards a more cohesive and user-friendly set of docs rather than fight fires as they emerge.

From reading this thread in terms of issues we have with the docs I see the following:

• Collectively, we're not entirely sold on the terminology of "Non-normative", so we need to agree whether we use it at all, and if we do we need to define this term for the readership (and ourselves).
• Related to this, the terms "Reference" and "Guidance" may need qualifying or defining, so that readers of the documentation will know what is normative content (reference) and what is not normative content (Guidance).
• The documentation is interactive and supports commenting via hypothesis, but there's little signposting of this and people may need some in-house guidance to support participating via hypothesis comments.

In the short term, we can address these by providing some content under an "About this site" or "About this documentation" heading as Greg suggests. I would hesitate creating another dedicated page in the already-quite-complex site structure so my suggestion is that we refactor the landing page to contain this.

Long-term, I think these immediate challenges demonstrate some of the underlying issues we should address in the documentation and governance. The following are my initial takes on these, but warrant further interrogation:

@greggish @mrshll1001 - Created a separate issue for what came next https://github.com/openreferral/specification/issues/475

[mrshll1001]

I've spun up a quick draft in a new branch of the docs called about-this-site. The landing page now has a section called "Using this documentation", which describes the Reference, Guidance, and Initiative sections of the site as well as signposts using Hypothes.is to create annotations.

It's branched off of the documentation-review branch so we can adjust accordingly and then merge back through once we're happy. I don't think this blocks us putting documentation-review live if there are delays.

[dan-odsc]

@greggish Are you happy with this?

[dan-odsc]

Related Planio issues for future reference (ODS use only) - https://opendataservices.plan.io/issues/44066

[dan-odsc]

@greggish Are you happy with this?

Can we close this issue @greggish

[greggish]

Hrm we'll have to tinker some more with this. a few things:

First, I can sort of guess what "normative" means but it's less clear what "not normative" means (at least to me, an English Major) so i'd still like us to offer explanations of each clause to clarify before saying whether the material does or does not take precedence.

Also, right now this still references the Project Documentation which we're moving out. So we'll probably want to revise that section – maybe removing most of it, while folding into it the Our Ecosystem section.

If you all can get me some language for the normative/non-normative definition in this context (or give me pointers to other similar context that I can reference to better understand and explain myself), then meanwhile I can work on the Project documentation revision stuff.

[dan-odsc]

Hi Greg,

• I think this definition/ wording could work https://os4d.opendataservices.coop/patterns/versioning/#pattern-normative

Also, right now this still references the Project Documentation which we're moving out. So we'll probably want to revise that section – maybe removing most of it, while folding into it the Our Ecosystem section. https://docs.openreferral.org/en/about-this-site/#our-ecosystem

• Matt is in the process of updating the docs to this effect as per #475. We’ll have a branch for you to review soon.

Dan

---

On Mon, 22 Jan 2024 at 20:02, Greg Bloom @.***> wrote:

Hrm we'll have to tinker some more with this. a few things:

First, I can sort of guess what "normative" means but it's less clear what "not normative" means (at least to me, an English Major) so i'd still like us to offer explanations of each clause to clarify before saying whether the material does or does not take precedence.

Also, right now this still references the Project Documentation which we're moving out. So we'll probably want to revise that section – maybe removing most of it, while folding into it the Our Ecosystem section. https://docs.openreferral.org/en/about-this-site/#our-ecosystem

If you all can get me some language for the normative/non-normative definition in this context (or give me pointers to other similar context that I can reference to better understand and explain myself), then meanwhile I can work on the Project documentation revision stuff.

— Reply to this email directly, view it on GitHub https://github.com/openreferral/specification/issues/459#issuecomment-1904716061, or unsubscribe https://github.com/notifications/unsubscribe-auth/A4PEV22MC44RWJXFFEE7CITYP3AVHAVCNFSM6AAAAAA5U7XA32VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMBUG4YTMMBWGE . You are receiving this because you authored the thread.Message ID: @.***>

[greggish]

Why can't we use "informative" instead of "non-normative"? If the IETF uses it, that seems like a valid precedent, and it has the advantage of being literally descriptive and not confusing.

[JimSaiya]

Yes, "informative" should be sufficient. The W3C's specs do use the term "non-normative", but also group references into "normative" and "informative" sections.

However, after a quick look through some of their policy documents, I couldn't find any definitions for those terms.

[dan-odsc]

Revised wording for the docs - https://docs.google.com/document/d/1SzXaFodaqCr3AhIWKqjLMVrojpCpqjS-SkAG1uClnpE/edit#heading=h.5dfe26ml5ai