Run PoC for using GitHub Docs for our tech docs

[mitovskaol]

We want to evaluate whether the GitHub Docs product to support our Technical Documentation portal (essentially replacing DevHub)

DoD:

• Assess and repo whether the Github Docs solution meets the mandatory requirements as listed here

Note: you may want to research if any other org uses GitHub Docs for their needs and what their experience is

[jleach]

Just started. Will mostly be a next sprint activity but I wanted to kick the tires to make sure it was doable before then.

Progress good. I have it running in docker with some edited content. The plan for next sprint is to become familiar with he mechanics of the server/language so that we can get a few pages being displayed.

At first glance GH seems to put lots of programatic idioms in it. Probably because they're such a larger org with logs of conditions. Will make sure we can simplify as needed.

[mitovskaol]

Thanks for the quick progress on this @jleach !! Can you please document in this ticket how the GitHub Docs meet or not meet the 5 main function requirements for our ideal Content Management System as documented here. Thanks!

[juhewitt]

Just adding reference for some existing GitHub Pages resources created by the Lab, other org, for a potential comparison ticket following @jleach's efforts on this ticket. Also adding a reference to developer.gov for the Design System, DataBC manual etc.

Exchange Lab Ops https://bcgov.github.io/ExchangeLabOps/

CITZ IMB Playbook https://bcgov.github.io/CITZ-IMB-playbook/

About The Design System https://developer.gov.bc.ca/Design-System/About-the-Design-System

BCData https://bcgov.github.io/bcdata/

[mitovskaol]

@juhewitt I LOVE the Exchange Lab Ops resource, can we just copy/reuse what they did with GitHub Docs instead of waiting for the WordPress?

[juhewitt]

Lets have Jason finish this ticket, and then review together. We want to know if ExchangeLab can incorporate search. In addition, I need to work with someone to create a mind map of all the repos developer.gov.bc.ca pulls from.

[jleach]

As of today, I find the product is quite good but I haven't found much documentation nohow to use it. For example, there is now how to build out your own instance of it. The repo is the actual one used by GitHub with all its content that gets packaged into the image at build time. To use it we need to figure out how it works, remove all the GitHub content, and then build up our own content. If we get there, we're in a good place. But without any documentation on how things work I feel like I'm using trial-and-error to figuring out how things work.

So far struggling a but to figure out how I can eliminate translations since our docs only come in one language ATM. Also, its quite resource intensive: Either my MacBook Pro is getting old and laggy or its taking quite a bit of effort for it to run the container locally.

[mitovskaol]

@jleach I wonder if maybe we may want to pause this R&D and look at GitHub Pages instead. From what I saw in their tech docs, it might be a better fit for us. LMK what you think.

[jleach]

@mitovskaol I think so. This might be a "run" in our playbook where as we are looking for a "crawl" to get us started. We can try GitHub Pages and if it starts to come up short we can do some more R&D into what "walk" looks like.

GitHub Pages was what we used for the old status page. I though they worked well enough. Should be find for a documentation PoC.

[juhewitt]

From sprint review, the team wants to use Gatsby -> https://www.gatsbyjs.com/docs/how-to/

This is good. please make sure we have a backlog item to create a separate instance for user testing. @mitovskaol @jleach

[jleach]

What we need for a tool is for it to take markdown files and render them as HTML with a similar layout the the British Gov site. Out of the tech I've looked at I think GitHub Docs is great but not usage is not well documented (if at all I couldn't find it). Documize is fine but not really the look we are after. I favour Gatsby with the documentation theme because its usable, well supported by the community, and best of all we have some expertise on the team with Gatsby (Patrick and Billy).

Moving this ticket back to the backlog until someone else can run with it.

[juhewitt]

@jleach can we close this ticket, and create a new one for creating a Gatsby PoC with gov look and feel in preparation for user testing with teh developers?

[mitovskaol]

Closing this ticket as the research will move to look at Gatsby which will be tracked in a separate ticket.