4253: Standardised documentation files - Composr CMS feature tracker

ID	Project	Category	View Status	Date Submitted	Last Update

4253	Composr	core	public	2020-05-27 03:15	2025-02-27 16:40

Reporter	Chris Graham	Assigned To	Chris Graham
Priority	normal	Severity	feature
Status	resolved	Resolution	fixed

Summary	4253: Standardised documentation files
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.
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
Tags	Roadmap: v11
Attach Tags	(Separate by ",")

Time estimation (hours)	4
Sponsorship open

Date Added	Member	Amount Sponsored

Date Modified	Username	Field	Change
2020-05-27 03:15	Chris Graham	New Issue
2020-05-27 03:15	Chris Graham	Tag Attached: Roadmap: v11
2020-05-27 03:15	Chris Graham	Relationship added	related to 4252
2020-06-02 22:37	Chris Graham	Assigned To	=> Chris Graham
2020-06-02 22:37	Chris Graham	Status	Not Assigned => Resolved
2020-06-02 22:37	Chris Graham	Resolution	open => fixed
2025-02-27 16:40	PDStig	Relationship added	related to 3843