#4253 - Standardised documentation files

Identifier #4253
Issue type Feature request or suggestion
Title Standardised documentation files
Status Completed
Tags

Roadmap: v11 (custom)

Handling member Chris Graham
Addon core
Description Standards have existed for Unixy projects for a long-time around having certain standardly-named files in a project folder.
For example, 'README'.

I ignored this with Composr because I thought that we should just standardise our documentation through the website.

Use of GitHub has made these old Unixy standards applicable more broadly I'd say. People may look for these files when browsing around on git repositories before they look at the website. There are standardised standards, such as codes of conducts, that are explicitly written for projects via these files. I myself have just proposed a new standard for documenting community support expectations (https://github.com/github/opensource.guide/issues/1635).

My view hasn't changed in the sense of having documentation standardised in the tutorials on the website.

However, it would not hurt to create the standard files as signposts through to the official documentation, and package them into the 'installer' addon, so that the Setup Wizard will (by default) be removing it after a completed installation.

This way, we get the best of both worlds.
Steps to reproduce

Additional information GitHub recognises a 'docs' directory as a standard. We already have a 'docs' directory in our Git repository (the tutorials are all under docs/pages/comcode_custom/EN), and we can certainly add more to it.

We'd create these files:
README.md - make new file, with links to some key tutorials and our website, including installation
LICENSE.md - move text/EN/licence.txt to here instead
THANKS.md - move credits out from licence.txt
CONTRIBUTING.md - link to appropriate tutorial
CHANGELOG.md - just link to GitLab commit history
AUTHORS.md - just link to GitLab commiter activity (if that's a thing, I'm not sure)
NEWS.md - just link to compo.sr news page
BUGS.md - link to tracker, link to appropriate tutorial
SUPPORT.md - link to appropriate tutorial
CODE_OF_CONDUCT.md - link to new tutorial (see #4252)
SECURITY.md - link to appropriate tutorial

References to review to make sure our documentation is covering all the right points, in a 'standard' way:
https://en.wikipedia.org/wiki/README
https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-readmes
https://help.github.com/en/github/building-a-strong-community/adding-a-code-of-conduct-to-your-project
https://help.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors
https://help.github.com/en/github/building-a-strong-community/adding-a-license-to-a-repository
https://help.github.com/en/github/building-a-strong-community/adding-support-resources-to-your-project
https://help.github.com/en/github/building-a-strong-community/creating-a-default-community-health-file
https://help.github.com/en/github/managing-security-vulnerabilities/adding-a-security-policy-to-your-repository
https://www.contributor-covenant.org/
https://opensource.guide/code-of-conduct/
https://opensource.guide/building-community/
https://opensource.guide/leadership-and-governance/
https://opensource.guide/getting-paid/
https://opensource.guide/best-practices/
https://github.com/github/opensource.guide/issues/1635
Funded? No
The system will post a comment when this issue is modified (e.g., status changes). To be notified of this, click "Enable comment notifications".

Rating

Unrated