Docs / website / education working group

[maximilien]

From last week’s TAC call we agreed to propose a working group for documentation / website / education.

Individuals interested in participating should comment on this issue for when the TAC approves this request.

[planetf1]

I'm Interested in participating, both on the technical/infrastructure, and content (guidance, process, tutorials etc) - albeit not from a cryptographic expertise perspective which is best left to overs. We do already have oqs level docs, and there's a project-level skeleton doc repo at https://github.com/pq-code-package/documentation for PQ-CP (mkdocs) modelled on hyperledger

[ajbozarth]

I am also interested in participating alongside Nigel

[Naomi-Wash]

I created a Google doc with the breakdown of how I see the content flowing across websites, pages, etc. I shared this with @planetf1 but want to have it here for reference as well. My suggestions are open for discussion and modification of course.

[planetf1]

I would like to propose that we use pq-code-package/documentation to start assembling docs - for example on security policy. Think of this as a development space - so we would add a caveat of being unapproved docs until gone through the pqca or pq-code-package tac/tsc

Ideally we don't want to write things twice, so new projects are likely to mostly refer to pqca level material. open-quantum-safe may be an exception as it's well-established.

In addition the initial number of contributors is likely small, and dealing with multiple sites is probably unnecessary overhead.

We can leave the repo (and website link) at the current location, add a redirect, or move to pqca if preferred.

Once we have more content we can review again, and split if desired.

pragmatic?

[planetf1]

@Naomi-Wash I was going to add an initial introduction to the workgroup.

However the repo is empty. I cannot create a fork to create a PR from. Nor do I have permission to create a branch on the main repo (which isn't a great approach anyway), and finally do not have permission to push direct to main so I can't add any content.

Could you grant me appropriate access - thanks

[planetf1]

The same will apply to wg-algorithms

[planetf1]

Discussed docs in tac call 20240605

Proposed we create a mkdocs-material based site similar to https://docs.pqcodepackage.org which itself was based on the hyperledger template.

A good start could be:

• create a copy of pq-code-package/documentation under pqca (if only as it has right icon etc). Not a fork
• have a CNAME docs.pqca.org

• setup access for myself+anyone in docs workgroup

  Ok? @maximilien If so can you help with the dns/permissions @ryjones ?

[ryjones]

@planetf1 Once we have a repo, I can set up the DNS

[planetf1]

@ryjones Initial website is now created

• repo: PQCA/documentation

• current URL: https://pqca.github.io/documentation

  I think we just need a custom DNS setup & the project settings updated - similar to what was done for pq-code-package

  The content needs more work I'll raise a separate PR on access control

[ryjones]

@planetf1 I re-added the CNAME (that is, I deleted your commit removing it)

https://docs.pqca.org/

[planetf1]

@ryjones The original cname was pulled in from the initial copy across. I then updated (global renames), but I couldn't publish properly as validation would fail, so I removed to at least have a working state.

The docs were rendering ok to github.io, but with the cname I'm just getting the readme not built page (as per https://docs.pqcodepackage.org/latest/) . Just checking ...

[planetf1]

@ryjones Think it just needed the branch corrected in settings. Updating.

[planetf1]

@ryjones looks good now. Thanks for doing the update