multiple updates to contributing page:

- add missing jump links
- re-order some sections for better flow and clarity
- add note about source code
- add additional info on github and how its used for contriubtions
This commit is contained in:
KemoNine 2023-03-21 13:38:05 -04:00
parent e8722e04e6
commit 99d12d7e27

View file

@ -14,23 +14,108 @@ tags:
## Changelog ## Changelog
{{< changelog >}} {{< changelog >}}
{{< change 2023-03-21 "Add missing jump links" >}}
{{< change 2023-03-21 "Re-order some sections for better flow and clarity" >}}
{{< change 2023-03-21 "Add note about source code" >}}
{{< change 2023-03-21 "Add additional info on GitHub and how it's used for contributions" >}}
{{< change 2023-03-21 "Add note that change log is exempt from 2nd level heading 'back to top'" >}} {{< change 2023-03-21 "Add note that change log is exempt from 2nd level heading 'back to top'" >}}
{{< change 2023-03-20 "Initial creation" >}} {{< change 2023-03-20 "Initial creation" >}}
{{< /changelog >}} {{< /changelog >}}
{{< end_section >}} {{< end_section >}}
## Source Code
{{< back_to_top >}}
The source code for the site can be found on GitHub [here](https://github.com/mcrosson/accessible.tips).
The site has been developed using [Hugo](https://gohugo.io/) and the main site pages are in the `content` directory of the `Code`
{{< end_section >}}
## Contributing ## Contributing
{{< back_to_top >}} {{< back_to_top >}}
We welcome contributions to the site and ask that you use our [GitHub repository](https://github.com/mcrosson/accessible.tips) for any contributions. We welcome contributions to the site and ask that you use our [GitHub repository](https://github.com/mcrosson/accessible.tips) for any contributions.
We welcome our user's feedback ; including but not limited to {{< back_to_top >}}
- Issue submissions ### Issues and Questions
- Code updates {{< back_to_top >}}
- Website content updates
- More If you run into any problems with the website or have specific questions, please use the `Issues` section of our GitHub repository [here](https://github.com/mcrosson/accessible.tips/issues).
We politely ask you review the open issues for exiting items that overlap. Please comment on an existing issue that is relevant prior to creating a new issue.
If there is not an exiting issue for your need, please create a new issue. We politely ask you provide us as much detail as possible so we can hopefully respond without having to play a game of 20 questions.
{{< back_to_top >}}
### Website Content Updates
{{< back_to_top >}}
We welcome updates to the contents of this website. Please use the `Issues` section [here](https://github.com/mcrosson/accessible.tips/issues) to submit any change requests for the site.
If you've used GitHub and git in the past, we will accept `Pull Requests` for updates. However, we will *not* describe the process here as it is an avanced topic we are not supporting directly. Consider `Pull Requests` a convenience that could go away in the future due to their inherent complexity.
{{< back_to_top >}}
### And More
{{< back_to_top >}}
Any other requests we ask be submitted as GitHub `Issues` [here](https://github.com/mcrosson/accessible.tips/issues).
{{< end_section >}}
## File and Folder Organization
{{< back_to_top >}}
Files and folders are setup with the following overall layout.
``` txt
/content/
tips/
category-topic-1.md
category-topic-2.md
category-topic-3/index.md
posts/yyyy-MM-dd-title.md
yyyy-MM-dd-title/index.md
faq/title-1.md
title-2/index.md
```
{{< back_to_top >}}
### Tips Directory
{{< back_to_top >}}
The `tips` directory contains the main knowledge base data. Each file represents a different page on the site and they are named using the format `[category]-[title].md` with `[category]` being the category set in the page metadata and `[title]` being the title set in the page metadata.
This allows us to easily cross reference information within a category (see [here]({{< ref "#cross-references" >}}) for how to cross reference pages) and keep the topic file names from colliding if there is any overlap between categories.
This rigid, tree'd structure is imposed by Hugo and we have adapted our file and folder organization to work with Hugo instead of against it.
This is also why we can have *only one* primary category for content currently.
We will also use `Page Bundles` ([Hugo docs](https://gohugo.io/content-management/page-bundles/)) for content that includes non-textual content or download links. `Page Bundles` are just folders with an `index.md` file and related assets. The `index.md` file is the main content and any files stored next to `index.md` can be easily referenced directly from `index.md`. This is particularly helpful for managing image assets and keeping them organized.
{{< back_to_top >}}
### Posts Directory
{{< back_to_top >}}
In this layout the `posts` directory contains all of the blog posts with dated file names using the given pattern. It's a pretty standard and simple folder organization scheme.
We will also use `Page Bundles` ([Hugo docs](https://gohugo.io/content-management/page-bundles/)) for content that includes non-textual content or download links. `Page Bundles` are just folders with an `index.md` file and related assets. The `index.md` file is the main content and any files stored next to `index.md` can be easily referenced directly from `index.md`. This is particularly helpful for managing image assets and keeping them organized.
{{< back_to_top >}}
### FAQ Directory
{{< back_to_top >}}
In this layout the `faq` directory contains all of the FAQ pages with file names matching the page title. It's a pretty standard and simple folder organization scheme.
We will also use `Page Bundles` ([Hugo docs](https://gohugo.io/content-management/page-bundles/)) for content that includes non-textual content or download links. `Page Bundles` are just folders with an `index.md` file and related assets. The `index.md` file is the main content and any files stored next to `index.md` can be easily referenced directly from `index.md`. This is particularly helpful for managing image assets and keeping them organized.
{{< end_section >}} {{< end_section >}}
@ -48,6 +133,7 @@ If submitting content or copy edits, please note the following
{{< end_section >}} {{< end_section >}}
## Authorship ## Authorship
{{< back_to_top >}}
Fell free set your preferred name as the author, we like to attribute our authors. If you prefer to remain anonymous, please set authorship to `Anonymous`. Fell free set your preferred name as the author, we like to attribute our authors. If you prefer to remain anonymous, please set authorship to `Anonymous`.
@ -56,12 +142,14 @@ Please note: Authorship metadata will be publicly visible.
{{< end_section >}} {{< end_section >}}
## Last Modified Date ## Last Modified Date
{{< back_to_top >}}
When editing an exiting post, we require you update the `lastMod` date in the front matter of all content pages. The date you use here should match the date used on the `Changelog` entry. See [Changelog Entries]({{< ref "#changelog-entries" >}}) for more info on `Changelog` dates. When editing an exiting post, we require you update the `lastMod` date in the front matter of all content pages. The date you use here should match the date used on the `Changelog` entry. See [Changelog Entries]({{< ref "#changelog-entries" >}}) for more info on `Changelog` dates.
{{< end_section >}} {{< end_section >}}
## Changelog Entries ## Changelog Entries
{{< back_to_top >}}
This site uses GitHub for tracking the changes to the content used to generate the site. Please consider GitHub the source of truth for the data contained on this website. This site uses GitHub for tracking the changes to the content used to generate the site. Please consider GitHub the source of truth for the data contained on this website.
@ -76,6 +164,7 @@ Programmers take note: this can be a copy/paste of your git commit. However, thi
{{< end_section >}} {{< end_section >}}
## Categories ## Categories
{{< back_to_top >}}
We have tried to keep categories to a small, very high level set and we would like to keep this list focused and small presently. We have tried to keep categories to a small, very high level set and we would like to keep this list focused and small presently.
@ -90,6 +179,7 @@ Please note: the submitted content page(s) do *not* have to be exhaustive or all
{{< end_section >}} {{< end_section >}}
## Tags ## Tags
{{< back_to_top >}}
We have tried to keep tags to a well curated list that help tie many different `Tips` togther. We have also tried to ensure tags are relevant to the category specified on each `Tip`. We have tried to keep tags to a well curated list that help tie many different `Tips` togther. We have also tried to ensure tags are relevant to the category specified on each `Tip`.
@ -102,6 +192,7 @@ Long term we hope to build a tag glossary to enhance discovery, search and synon
{{< end_section >}} {{< end_section >}}
## Cross References ## Cross References
{{< back_to_top >}}
If you are cross referencing information you can use the following code. If you are cross referencing information you can use the following code.
@ -109,42 +200,4 @@ If you are cross referencing information you can use the following code.
Please use this format for cross references between content pages. It helps us better manage cross references between content pages over time. Please use this format for cross references between content pages. It helps us better manage cross references between content pages over time.
{{< end_section >}}
## File and Folder Organization
Files and folders are setup with the following overall layout.
``` txt
/content/
tips/
category-topic_1.md
category-topic_2.md
category-topic_3/index.md
posts/yyyy-MM-dd-title.md
yyyy-MM-dd-title/index.md
```
{{< back_to_top >}}
### Tips Directory
The `tips` directory contains the main knowledge base data. Each file represents a different page on the site and they are named using the format `[category]-[title].md` with `[category]` being the category set in the page metadata and `[title]` being the title set in the page metadata.
This allows us to easily cross reference information within a category (see [here]({{< ref "#cross-references" >}}) for how to cross reference pages) and keep the topic file names from colliding if there is any overlap between categories.
This rigid, tree'd structure is imposed by Hugo and we have adapted our file and folder organization to work with Hugo instead of against it.
This is also why we can have *only one* primary category for content currently.
We will also use `Page Bundles` ([Hugo docs](https://gohugo.io/content-management/page-bundles/)) for content that includes non-textual content or download links. `Page Bundles` are just folders with an `index.md` file and related assets. The `index.md` file is the main content and any files stored next to `index.md` can be easily referenced directly from `index.md`. This is particularly helpful for managing image assets and keeping them organized.
{{< back_to_top >}}
### Posts Directory
In this layout the `posts` directory contains all of the blog posts with dated file names using the given pattern. It's a pretty standard and simple folder organization scheme.
We will also use `Page Bundles` ([Hugo docs](https://gohugo.io/content-management/page-bundles/)) for content that includes non-textual content or download links. `Page Bundles` are just folders with an `index.md` file and related assets. The `index.md` file is the main content and any files stored next to `index.md` can be easily referenced directly from `index.md`. This is particularly helpful for managing image assets and keeping them organized.
{{< back_to_top >}} {{< back_to_top >}}