APS-4241 Initial Draft of Getting Started content

[phowells]

Updated to reflect content provided by Tanya in this document

https://bcgov-my.sharepoint.com/:w:/r/personal/tanya_riemann_gov_bc_ca/Documents/Connected%20Services%20Content/v2%20-%20ConnectedServices_Content%20SW%20Review.docx?d=wefb75eb9296a48168114738574fcaf11&csf=1&web=1&e=gfyaF5

[dstainton]

designation

[dstainton]

I added a few comments related to authoritative data - 'certification' is now 'designation' so all references to certification/certified etc. will need to be updated. Otherwise it's good to go.

[rustyjux]

Looks good overall. I only skimmed the content and have not given feedback on it, since I assume that wasn't why I was tagged here.

I left a few comments re: conventions - most are opinionated and not required changes.

[rustyjux]

This seems like an odd convention to have a constant level one title (though maybe was in Tanya's specification). This is contrary to what we (APS) and DevEx do in their docs, but I guess it's fine if that's the convention we want to follow for this project.

[rustyjux]

Looking at the word doc draft, I don't see this as a requirement. I'd suggest removing this line from all pages and promoting all headings up one level.

And I would reinforce my other recommendation to specify a title in the front matter:

---
title: Authoritative Data Register (ADR)
---

this title will show in the sidebar nav and top of the page as H1. If you want a different title to display as H1 (e.g. a longer title than in the sidebar nav), then you can include a level one heading.

It's sort of up to you if you want to keep the H1 in each doc duplicating what is the in the title, but for APS docs we omitted it and just use the front matter.

[rustyjux]

Not a huge deal but to me this is an (annoying) anti-pattern. Instead of needing to specify the title twice, just use the level one header from the document or specify a title in the front matter, e.g. as in https://github.com/bcgov/aps-infra-platform/blob/test/documentation/how-to/create-gateway.md?plain=1#L1C1-L3C4

Suggested change

	- Purpose and value: getting-started/purpose-and-value.md
	- getting-started/purpose-and-value.md

[rustyjux]

Just a heads up that regardless of what is here in mkdocs.yml, or in the H1 or front-matter title, the HTML page <title> comes from the path / file name.

So really my suggestion is to keep the page titles within the docs, as opposed to duplicating here in mkdocs.yml.

[rustyjux]

Blank lines between list items seems like a bad convention. It is harder to read the markdown and (more importantly) adds extra vertical spacing in the rendered output, making the list look 'loose'.

Do keep a blank line before the list.

[rustyjux]

Avoid 'TechDocs' - the meaning is intuitive enough, but no one needs to know that TechDocs is powering the backend here.

I'd suggest 'Documentation' or 'Technical Documentation'.

For comparison, see other docs in https://developer.gov.bc.ca/docs

This is not the source of truth for the content yet so making changes here will only be overwritten with the next update.