Guidance pages

[rmccreath]

Pull Request Details

Type: Feature

Issue: Closes #31

Description of the Change

• Added a page for docs
  • Currently hidden from nav for testing purposes
  • Also using template repo for testing: https://github.com/Public-Health-Scotland/technical-docs
  • Please access live here: https://public-health-scotland.github.io/knowledge-base/docs
• Uses the GitHub API to pull top-level directories and docs for navigation
• Uses the GitHub API to pull markdown documents and renders them on site
• Search functionality to search doc titles
• Button on docs to link back to GitHub page
• Where links to repo docs are relative on Markdown, the site should allow internal navigation (at least one test is included)
• External links should open in new tab
• Directory links in nav should pull directory level README file
• The URL should update for each document (meaning we can send these as links to users)

Looking for first user testing, please explore the link above and provide any feedback here. I'm not expecting a code review for this, however, if anyone is interested, feel free to have a look (I do need to spend some time tidying it though).

Possible Drawbacks

This will require a restructure and rename for the R-resources repo on GitHub, or the template (technical-docs) repo can pull across the relevant documentation. As R-resources was created for a specific R textbook, it might be better to move the documentation out of there?

There will also need to be a structured approach to how docs are added and maintained, including filename and internal links, to ensure they work as part of the process.

[terrymclaughlin]

@rmccreath

I've not reviewed your code, but I've reviewed the page you linked to with the template documentation pages.

This looks good to me, with one suggestion: can the "Docs" page be renamed to "Documentation" or "Documentation, Guidance and Best Practice"?

[rmccreath]

This looks good to me, with one suggestion: can the "Docs" page be renamed to "Documentation" or "Documentation, Guidance and Best Practice"?

Hey @terrymclaughlin - updated the title, should be live in the next couple mins :)

[fraserstirrat]

Reviewed the description of changes and the page where the link takes you (not reviewed any code).
All looks good, don't have anything to add 😀

[CliveWG]

This is great work and will be a real asset for the organisation :-)

Again as Fraser did, I just reviewed your pull request details/ description of change document and all links.

All seems good.

There are just a couple of points to mentioned in terms of the linked areas:

under Infrastructure then Log in and start a session on Posit Workbench

As this is aimed at people new to Posit, I wondered if the diagram under 7 needs to be the uncluttered version, without any projects shown, so as not to confuse users. No new user will have any projects shown? Sadly I have recently used Jupyter so mine is now cluttered with that project!

under Posit workbench and Kubernates

Last paragraph under autoscaling

The bit about it generally taking a few seconds to load - is it just me, it's not often if ever that it has taken just a few seconds to load, not at early hours or in the daytime or eve. I think that it’s worth testing the time that a new session takes to start – I have tested this today admittedly not using a superfast high speed broadband and takes between 40 and 50 seconds. In the next day or two, I shall be able to test using a superfast high speed broadband.

[rmccreath]

There are just a couple of points to mentioned in terms of the linked areas:

Hey, @CliveWG - these comments relate to the specific guidance which is hosted separately. The 2 docs I used were pulled from the written guidance as a test. For changes to these, the actual documents should be changed which will automatically populate on the knowledge base with these changes.

If that's the feedback though, I'm assuming the changes are good 😄