From 39fab57fa2ba74c07ba0a4fd0abc286fe29dd9a0 Mon Sep 17 00:00:00 2001 From: Joy A Date: Mon, 7 Oct 2024 14:13:02 +0100 Subject: [PATCH 1/6] Creative Common Technical Documentation Guideling blog added --- content/blog/authors/Dev-JoyA/contents.lr | 10 ++ .../technical-docs-guidelines/contents.lr | 139 ++++++++++++++++++ 2 files changed, 149 insertions(+) create mode 100644 content/blog/authors/Dev-JoyA/contents.lr create mode 100644 content/contributing-code/technical-docs-guidelines/contents.lr diff --git a/content/blog/authors/Dev-JoyA/contents.lr b/content/blog/authors/Dev-JoyA/contents.lr new file mode 100644 index 00000000..2e8423c6 --- /dev/null +++ b/content/blog/authors/Dev-JoyA/contents.lr @@ -0,0 +1,10 @@ +username: Dev-JoyA +--- +name: Joy Aruku +--- +md5_hashed_email: +--- +about: +Joy Aruku is a MERN stack web developer based in Lagos, Nigeria. + + diff --git a/content/contributing-code/technical-docs-guidelines/contents.lr b/content/contributing-code/technical-docs-guidelines/contents.lr new file mode 100644 index 00000000..fd8a7ccd --- /dev/null +++ b/content/contributing-code/technical-docs-guidelines/contents.lr @@ -0,0 +1,139 @@ +_model: page +--- +_template: page-with-toc.html +--- +title: Technical Documentation Guidelines +--- +description: This Technical documentaion guidelines (style guide) ensuures all the readme on all repository and any other technical docs are properly documented . +--- +body: + +## Technical Documentation Guidelines +The purpose of this guideline is to provide a step-by-step framework for writing and maintaining high-quality technical documentation for Creative Commons (CC) projects. This guide covers essential sections that should be included in the documentation, such as project overview, code of conduct, contributing instructions, installation, development, and deployment. Following these guidelines will ensure consistency, clarity, and ease of use for all contributors and users. + +## Style Guide Reference + +For general writing style and guidelines, refer to the following upstream style guides: + +- [Google Developer Style Guide]: (https://developers.google.com/style/) +- [Microsoft Writing Style Guide]: (https://learn.microsoft.com/en-us/style-guide/welcome/) + +## Style Preferences Modifications + +While adhering to the upstream style guides, the following modifications should be observed: + +- Use active voice wherever possible to improve clarity and engagement. +- Keep sentences concise and to the point, avoiding jargon unless necessary. + +## Overview + +The Overview section provides a summary of the project and general information that users or contributors need to know. It should include + +- Repository information: Include the link to the GitHub repository and a brief description of the project. +- Tech stack: List the technologies used to build the project (e.g., Python, Django, Jekyll, JavaScript). + +## Code of conduct +The Code of Conduct section ensures that all contributors are aware of the community standards and acceptable behavior. It should include + +- A brief statement referring to the project's code of conduct +- A link to the full CODE_OF_CONDUCT.md file in the repository +- Information on how to report issues or violations. +[org-coc]: https://github.com/creativecommons/.github/blob/main/CODE_OF_CONDUCT.md +[code_of_conduct]: https://opensource.creativecommons.org/community/code-of-conduct/ +[reporting_guide]: https://opensource.creativecommons.org/community/code-of-conduct/enforcement/ + +## Contributing +The Contributing section provides details for those who wish to contribute to the project, and ensuring they follow the right process. + +- A link to the contribution guideline file in the repository. +- GitHub Pull Request (PR) guidelines. +- Link to repository guideline +[Contribution guideline] : https://opensource.creativecommons.org/contributing-code/ +[GitHub PR guideline]: https://opensource.creativecommons.org/contributing-code/pr-guidelines/ +[Repository guideline]: https://opensource.creativecommons.org/contributing-code/github-repo-guidelines/ + + +## Installation +The Installation section guides users through setting up the project on their local machines. + +- A list of prerequisites +- A detailed step-by-step instructions on how to install the necessary dependencies and tools. +- Instructions on how to clone the repository and set up the environment. + +### Development + +The **Development** section provides detailed instructions for contributors on how to run and develop the project locally. + +**What to include:** +- Instructions on how to start the local development environment. +- Steps for running the project and viewing changes. +- Any necessary setup (e.g., database, environment variables). + +### Deployment + +The **Deployment** section includes the steps needed to deploy the application. + +**What to include:** +- Deployment prerequisites (if any). +- Step-by-step instructions for deploying the project to the production environment. +- Configuration details for cloud services or hosting providers (e.g., GitHub Pages, AWS). if any + +### Markdown Syntax Usage + +This section offers guidance on how to use Markdown effectively in documentation. + +**Basic Syntax:** +- **Headings**: Use `#` for headings and additional `#` symbols for subheadings. + ```markdown + + # Heading 1 + ## Heading 2 + ### Heading 3 + +Lists: + +Unordered list: +markdown + +- First item +- Second item + +Ordered list: +markdown + +1. First item +2. Second item + +Links: +markdown + +[Link](url) + +Images: +markdown + +![Alt Text](url) + +Code Blocks: +markdown + ``` + code command + ``` + +Tables: +markdown + +| Header 1 | Header 2 | +|----------|----------| +| Content 1 | Content 2 | + + +## Terminology + +Establishing a clear "Terminology" section for Creative Commons (CC)-specific usage is crucial. Below are some proprietary terms and their usage: + +- **Creative Commons (CC)**: A non-profit organization that enables sharing and reuse of creative works. +- **Licenses**: Legal tools that allow creators to specify how their works can be used. +- **Attribution**: Giving credit to the creator of a work, which is a requirement in many CC licenses. + +Note : use the code Block markdon for instruction on installation, deployment, and development ... especially to write code commands \ No newline at end of file From 937173f37ad76c2f661eead14fcb0ef13b76d3d8 Mon Sep 17 00:00:00 2001 From: Joy A Date: Tue, 8 Oct 2024 16:33:44 +0100 Subject: [PATCH 2/6] Moved the technical document guideline from content.lr to a html page in templtes folder --- .../technical-docs-guidelines/contents.lr | 139 ------------------ .../templates/technical-docs-guide.html | 99 +++++++++++++ 2 files changed, 99 insertions(+), 139 deletions(-) delete mode 100644 content/contributing-code/technical-docs-guidelines/contents.lr create mode 100644 themes/vocabulary_theme/templates/technical-docs-guide.html diff --git a/content/contributing-code/technical-docs-guidelines/contents.lr b/content/contributing-code/technical-docs-guidelines/contents.lr deleted file mode 100644 index fd8a7ccd..00000000 --- a/content/contributing-code/technical-docs-guidelines/contents.lr +++ /dev/null @@ -1,139 +0,0 @@ -_model: page ---- -_template: page-with-toc.html ---- -title: Technical Documentation Guidelines ---- -description: This Technical documentaion guidelines (style guide) ensuures all the readme on all repository and any other technical docs are properly documented . ---- -body: - -## Technical Documentation Guidelines -The purpose of this guideline is to provide a step-by-step framework for writing and maintaining high-quality technical documentation for Creative Commons (CC) projects. This guide covers essential sections that should be included in the documentation, such as project overview, code of conduct, contributing instructions, installation, development, and deployment. Following these guidelines will ensure consistency, clarity, and ease of use for all contributors and users. - -## Style Guide Reference - -For general writing style and guidelines, refer to the following upstream style guides: - -- [Google Developer Style Guide]: (https://developers.google.com/style/) -- [Microsoft Writing Style Guide]: (https://learn.microsoft.com/en-us/style-guide/welcome/) - -## Style Preferences Modifications - -While adhering to the upstream style guides, the following modifications should be observed: - -- Use active voice wherever possible to improve clarity and engagement. -- Keep sentences concise and to the point, avoiding jargon unless necessary. - -## Overview - -The Overview section provides a summary of the project and general information that users or contributors need to know. It should include - -- Repository information: Include the link to the GitHub repository and a brief description of the project. -- Tech stack: List the technologies used to build the project (e.g., Python, Django, Jekyll, JavaScript). - -## Code of conduct -The Code of Conduct section ensures that all contributors are aware of the community standards and acceptable behavior. It should include - -- A brief statement referring to the project's code of conduct -- A link to the full CODE_OF_CONDUCT.md file in the repository -- Information on how to report issues or violations. -[org-coc]: https://github.com/creativecommons/.github/blob/main/CODE_OF_CONDUCT.md -[code_of_conduct]: https://opensource.creativecommons.org/community/code-of-conduct/ -[reporting_guide]: https://opensource.creativecommons.org/community/code-of-conduct/enforcement/ - -## Contributing -The Contributing section provides details for those who wish to contribute to the project, and ensuring they follow the right process. - -- A link to the contribution guideline file in the repository. -- GitHub Pull Request (PR) guidelines. -- Link to repository guideline -[Contribution guideline] : https://opensource.creativecommons.org/contributing-code/ -[GitHub PR guideline]: https://opensource.creativecommons.org/contributing-code/pr-guidelines/ -[Repository guideline]: https://opensource.creativecommons.org/contributing-code/github-repo-guidelines/ - - -## Installation -The Installation section guides users through setting up the project on their local machines. - -- A list of prerequisites -- A detailed step-by-step instructions on how to install the necessary dependencies and tools. -- Instructions on how to clone the repository and set up the environment. - -### Development - -The **Development** section provides detailed instructions for contributors on how to run and develop the project locally. - -**What to include:** -- Instructions on how to start the local development environment. -- Steps for running the project and viewing changes. -- Any necessary setup (e.g., database, environment variables). - -### Deployment - -The **Deployment** section includes the steps needed to deploy the application. - -**What to include:** -- Deployment prerequisites (if any). -- Step-by-step instructions for deploying the project to the production environment. -- Configuration details for cloud services or hosting providers (e.g., GitHub Pages, AWS). if any - -### Markdown Syntax Usage - -This section offers guidance on how to use Markdown effectively in documentation. - -**Basic Syntax:** -- **Headings**: Use `#` for headings and additional `#` symbols for subheadings. - ```markdown - - # Heading 1 - ## Heading 2 - ### Heading 3 - -Lists: - -Unordered list: -markdown - -- First item -- Second item - -Ordered list: -markdown - -1. First item -2. Second item - -Links: -markdown - -[Link](url) - -Images: -markdown - -![Alt Text](url) - -Code Blocks: -markdown - ``` - code command - ``` - -Tables: -markdown - -| Header 1 | Header 2 | -|----------|----------| -| Content 1 | Content 2 | - - -## Terminology - -Establishing a clear "Terminology" section for Creative Commons (CC)-specific usage is crucial. Below are some proprietary terms and their usage: - -- **Creative Commons (CC)**: A non-profit organization that enables sharing and reuse of creative works. -- **Licenses**: Legal tools that allow creators to specify how their works can be used. -- **Attribution**: Giving credit to the creator of a work, which is a requirement in many CC licenses. - -Note : use the code Block markdon for instruction on installation, deployment, and development ... especially to write code commands \ No newline at end of file diff --git a/themes/vocabulary_theme/templates/technical-docs-guide.html b/themes/vocabulary_theme/templates/technical-docs-guide.html new file mode 100644 index 00000000..902a0f87 --- /dev/null +++ b/themes/vocabulary_theme/templates/technical-docs-guide.html @@ -0,0 +1,99 @@ +{% extends "layout.html" %} + +{% block title %}Technical Documentation Guidelines{% endblock %} + +{% block body %} +
+
+
+

Technical Documentation Guidelines

+

+ This Technical Documentation Guidelines (style guide) ensures all the README files in all repositories and any other technical documentation are properly documented. +

+
+
+
+

The purpose of this guideline is to provide a step-by-step framework for writing and maintaining high-quality technical documentation for Creative Commons (CC) projects. This guide covers essential sections such as project overview, code of conduct, contributing instructions, installation, development, and deployment. Following these guidelines ensures consistency, clarity, and ease of use for all contributors and users.

+ +

Style Guide Reference

+

For general writing style and guidelines, refer to the following upstream style guides:

+ + +

Style Preferences Modifications

+

While adhering to the upstream style guides, observe the following modifications:

+
    +
  • Use active voice wherever possible to improve clarity and engagement.
    • +
  • Keep sentences concise and to the point, avoiding jargon unless necessary.
    • +
+ +

Overview

+

The Overview section provides a summary of the project and general information for users or contributors. It should include:

+
    +
  • Repository information: Include the link to the GitHub repository and a brief description of the project.
    • +
  • Tech stack: List the technologies used to build the project (e.g., Python, Django, Jekyll, JavaScript).
    • +
+ +

Code of Conduct

+

The Code of Conduct section ensures that all contributors are aware of community standards and acceptable behavior. It should include:

+
    +
  • A brief statement referring to the project's code of conduct.
    • +
  • A link to the full CODE_OF_CONDUCT.md file in the repository.
    • +
  • Information on how to report issues or violations.
    • +
+ +

Contributing

+

The Contributing section provides details for those who wish to contribute to the project, ensuring they follow the right process. Include:

+ + +

Installation

+

The Installation section guides users through setting up the project locally:

+
    +
  • A list of prerequisites.
    • +
  • Detailed step-by-step instructions for installing the necessary dependencies and tools.
    • +
  • Instructions on how to clone the repository and set up the environment.
    • +
+ +

Development

+

Provide detailed instructions for contributors on how to run and develop the project locally:

+
    +
  • Instructions on how to start the local development environment.
    • +
  • Steps for running the project and viewing changes.
    • +
  • Any necessary setup (e.g., database, environment variables).
    • +
+ +

Deployment

+

The Deployment section includes the steps needed to deploy the application:

+
    +
  • Deployment prerequisites (if any).
    • +
  • Step-by-step instructions for deploying the project to the production environment.
    • +
  • Configuration details for cloud services or hosting providers (e.g., GitHub Pages, AWS).
    • +
+ +

Markdown Usage

+

This section provides guidelines for using Markdown in documentation:

+ +

Note: Use code block markup for instructions on installation, deployment, and development, especially to write code commands.

+ + +

Terminology

+

Establishing a clear "Terminology" section for Creative Commons (CC)-specific usage is crucial. Below are some proprietary terms and their usage:

+
    +
  • Creative Commons (CC): A non-profit organization enabling sharing and reuse of creative works.
    • +
  • Licenses: Legal tools that allow creators to specify how their works can be used.
    • +
  • Attribution: Giving credit to the creator of a work, required in many CC licenses.
    • +
+ + +
+
+{% endblock %} From 89c4b0234fdc236285bebec877d9bc8ab3dfe985 Mon Sep 17 00:00:00 2001 From: Joy A Date: Wed, 9 Oct 2024 17:06:35 +0100 Subject: [PATCH 3/6] Removed technical docs guideline from templates to content/contributing code , added markdown to documentaion guideline --- .../documentation-guidelines/contents.lr | 10 ++ .../technical-docs-guidelines/contents.lr | 81 +++++++++++++++ .../templates/technical-docs-guide.html | 99 ------------------- 3 files changed, 91 insertions(+), 99 deletions(-) create mode 100644 content/contributing-code/documentation-guidelines/contents.lr create mode 100644 content/contributing-code/technical-docs-guidelines/contents.lr delete mode 100644 themes/vocabulary_theme/templates/technical-docs-guide.html diff --git a/content/contributing-code/documentation-guidelines/contents.lr b/content/contributing-code/documentation-guidelines/contents.lr new file mode 100644 index 00000000..d250ff50 --- /dev/null +++ b/content/contributing-code/documentation-guidelines/contents.lr @@ -0,0 +1,10 @@ +title: Documentation Guidelines + + + - ### Markdown Usage + This section provides guidelines for using Markdown in documentation: + - For comprehensive documentation on GitHub-flavored Markdown, refer to the [GitHub Markdown Guide](https://docs.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax). + - For additional information on the specific Markdown implementation used in Lektor, visit the [Lektor Markdown Documentation](https://www.getlektor.com/docs/content/#markdown). + - Note: Use code block markup for instructions on installation, deployment, and development, especially to write code commands. + + \ No newline at end of file diff --git a/content/contributing-code/technical-docs-guidelines/contents.lr b/content/contributing-code/technical-docs-guidelines/contents.lr new file mode 100644 index 00000000..7b81963c --- /dev/null +++ b/content/contributing-code/technical-docs-guidelines/contents.lr @@ -0,0 +1,81 @@ +title: Technical Documentation Guidelines +description: This Technical Documentation Guidelines (style guide) ensures all the README files in all repositories and any other technical documentation are properly documented. + +--- +# Technical Documentation Guidelines + +This Technical Documentation Guidelines (style guide) ensures all the README files in all repositories and any other technical documentation are properly documented. + +The purpose of this guideline is to provide a step-by-step framework for writing and maintaining high-quality technical documentation for Creative Commons (CC) projects. This guide covers essential sections such as project overview, code of conduct, contributing instructions, installation, development, and deployment. Following these guidelines ensures consistency, clarity, and ease of use for all contributors and users. + +## Style Guide Reference + +For general writing style and guidelines, refer to the following upstream style guides: + +- [Google Developer Style Guide (Preferred)](https://developers.google.com/style/) +- [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) + +## Style Preferences Modifications + +While adhering to the upstream style guides, observe the following modifications: + +- Use active voice wherever possible to improve clarity and engagement. +- Keep sentences concise and to the point, avoiding jargon unless necessary. + +## Overview + +The Overview section provides a summary of the project and general information for users or contributors. It should include: + +- **Repository information**: Include the link to the GitHub repository and a brief description of the project. +- **Tech stack**: List the technologies used to build the project (e.g., Python, Django, Jekyll, JavaScript). + +## Code of Conduct + +The Code of Conduct section ensures that all contributors are aware of community standards and acceptable behavior. It should include: + +- A brief statement referring to the project's code of conduct. +- A link to the full [CODE_OF_CONDUCT.md](https://github.com/creativecommons/.github/blob/main/CODE_OF_CONDUCT.md) file in the repository. +- Information on how to report issues or violations. + +## Contributing + +The Contributing section provides details for those who wish to contribute to the project, ensuring they follow the right process. Include: + +- A link to the [contribution guideline](https://opensource.creativecommons.org/contributing-code/) file in the repository. +- GitHub Pull Request (PR) guidelines. +- [Repository guideline](https://opensource.creativecommons.org/contributing-code/github-repo-guidelines/). + +## Installation + +The Installation section guides users through setting up the project locally: + +- A list of prerequisites. +- Detailed step-by-step instructions for installing the necessary dependencies and tools. +- Instructions on how to clone the repository and set up the environment. + +## Development + +Provide detailed instructions for contributors on how to run and develop the project locally: + +- Instructions on how to start the local development environment. +- Steps for running the project and viewing changes. +- Any necessary setup (e.g., database, environment variables). + +## Deployment + +The Deployment section includes the steps needed to deploy the application: + +- Deployment prerequisites (if any). +- Step-by-step instructions for deploying the project to the production environment. +- Configuration details for cloud services or hosting providers (e.g., GitHub Pages, AWS). + + +**Note**: Use code block markup for instructions on installation, deployment, and development, especially to write code commands. + +## Terminology + +Establishing a clear "Terminology" section for Creative Commons (CC)-specific usage is crucial. Below are some proprietary terms and their usage: + +- **Creative Commons (CC)**: A non-profit organization enabling sharing and reuse of creative works. +- **Licenses**: Legal tools that allow creators to specify how their works can be used. +- **Attribution**: Giving credit to the creator of a work, required in many CC licenses. diff --git a/themes/vocabulary_theme/templates/technical-docs-guide.html b/themes/vocabulary_theme/templates/technical-docs-guide.html deleted file mode 100644 index 902a0f87..00000000 --- a/themes/vocabulary_theme/templates/technical-docs-guide.html +++ /dev/null @@ -1,99 +0,0 @@ -{% extends "layout.html" %} - -{% block title %}Technical Documentation Guidelines{% endblock %} - -{% block body %} -
-
-
-

Technical Documentation Guidelines

-

- This Technical Documentation Guidelines (style guide) ensures all the README files in all repositories and any other technical documentation are properly documented. -

-
-
-
-

The purpose of this guideline is to provide a step-by-step framework for writing and maintaining high-quality technical documentation for Creative Commons (CC) projects. This guide covers essential sections such as project overview, code of conduct, contributing instructions, installation, development, and deployment. Following these guidelines ensures consistency, clarity, and ease of use for all contributors and users.

- -

Style Guide Reference

-

For general writing style and guidelines, refer to the following upstream style guides:

- - -

Style Preferences Modifications

-

While adhering to the upstream style guides, observe the following modifications:

-
    -
  • Use active voice wherever possible to improve clarity and engagement.
    • -
  • Keep sentences concise and to the point, avoiding jargon unless necessary.
    • -
- -

Overview

-

The Overview section provides a summary of the project and general information for users or contributors. It should include:

-
    -
  • Repository information: Include the link to the GitHub repository and a brief description of the project.
    • -
  • Tech stack: List the technologies used to build the project (e.g., Python, Django, Jekyll, JavaScript).
    • -
- -

Code of Conduct

-

The Code of Conduct section ensures that all contributors are aware of community standards and acceptable behavior. It should include:

-
    -
  • A brief statement referring to the project's code of conduct.
    • -
  • A link to the full CODE_OF_CONDUCT.md file in the repository.
    • -
  • Information on how to report issues or violations.
    • -
- -

Contributing

-

The Contributing section provides details for those who wish to contribute to the project, ensuring they follow the right process. Include:

- - -

Installation

-

The Installation section guides users through setting up the project locally:

-
    -
  • A list of prerequisites.
    • -
  • Detailed step-by-step instructions for installing the necessary dependencies and tools.
    • -
  • Instructions on how to clone the repository and set up the environment.
    • -
- -

Development

-

Provide detailed instructions for contributors on how to run and develop the project locally:

-
    -
  • Instructions on how to start the local development environment.
    • -
  • Steps for running the project and viewing changes.
    • -
  • Any necessary setup (e.g., database, environment variables).
    • -
- -

Deployment

-

The Deployment section includes the steps needed to deploy the application:

-
    -
  • Deployment prerequisites (if any).
    • -
  • Step-by-step instructions for deploying the project to the production environment.
    • -
  • Configuration details for cloud services or hosting providers (e.g., GitHub Pages, AWS).
    • -
- -

Markdown Usage

-

This section provides guidelines for using Markdown in documentation:

- -

Note: Use code block markup for instructions on installation, deployment, and development, especially to write code commands.

- - -

Terminology

-

Establishing a clear "Terminology" section for Creative Commons (CC)-specific usage is crucial. Below are some proprietary terms and their usage:

-
    -
  • Creative Commons (CC): A non-profit organization enabling sharing and reuse of creative works.
    • -
  • Licenses: Legal tools that allow creators to specify how their works can be used.
    • -
  • Attribution: Giving credit to the creator of a work, required in many CC licenses.
    • -
- - -
-
-{% endblock %} From a3834891cf1070a542d837a96b81d0868a73d23a Mon Sep 17 00:00:00 2001 From: Joy A Date: Thu, 10 Oct 2024 10:46:26 +0100 Subject: [PATCH 4/6] Removed README from documentaion-guidelines --- .../documentation-guidelines/contents.lr | 30 +++++++ .../technical-docs-guidelines/contents.lr | 81 ------------------- 2 files changed, 30 insertions(+), 81 deletions(-) delete mode 100644 content/contributing-code/technical-docs-guidelines/contents.lr diff --git a/content/contributing-code/documentation-guidelines/contents.lr b/content/contributing-code/documentation-guidelines/contents.lr index d250ff50..04531a4c 100644 --- a/content/contributing-code/documentation-guidelines/contents.lr +++ b/content/contributing-code/documentation-guidelines/contents.lr @@ -1,4 +1,34 @@ title: Documentation Guidelines +description: This Documentation Guidelines (style guide) ensures all the files in all repositories and any other documentation are properly documented. + +--- +# Documentation Guidelines + +The purpose of this guideline is to provide a step-by-step framework for writing and maintaining high-quality documentation for Creative Commons (CC) projects. This guide covers essential sections such as project style guide Preference, Style modification, terminologies, markdown usage. Following these guidelines ensures consistency, clarity, and ease of use for all contributors and users. + + ## Style Guide Reference + + For general writing style and guidelines, refer to the following upstream style guides: + + - [Google Developer Style Guide (Preferred)](https://developers.google.com/style/) + - [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) + + ## Style Preferences Modifications + + While adhering to the upstream style guides, observe the following modifications: + - All acronyms must be defined on first use + - Use active voice wherever possible to improve clarity and engagement. + - Keep sentences concise and to the point, avoiding jargon unless necessary. + + + ## Terminology + + Establishing a clear "Terminology" section for Creative Commons (CC)-specific usage is crucial. Below are some proprietary terms and their usage: + + - **Creative Commons (CC)**: A non-profit organization enabling sharing and reuse of creative works. + - **Licenses**: Legal tools that allow creators to specify how their works can be used. + - **Attribution**: Giving credit to the creator of a work, required in many CC licenses. + - ### Markdown Usage diff --git a/content/contributing-code/technical-docs-guidelines/contents.lr b/content/contributing-code/technical-docs-guidelines/contents.lr deleted file mode 100644 index 7b81963c..00000000 --- a/content/contributing-code/technical-docs-guidelines/contents.lr +++ /dev/null @@ -1,81 +0,0 @@ -title: Technical Documentation Guidelines -description: This Technical Documentation Guidelines (style guide) ensures all the README files in all repositories and any other technical documentation are properly documented. - ---- -# Technical Documentation Guidelines - -This Technical Documentation Guidelines (style guide) ensures all the README files in all repositories and any other technical documentation are properly documented. - -The purpose of this guideline is to provide a step-by-step framework for writing and maintaining high-quality technical documentation for Creative Commons (CC) projects. This guide covers essential sections such as project overview, code of conduct, contributing instructions, installation, development, and deployment. Following these guidelines ensures consistency, clarity, and ease of use for all contributors and users. - -## Style Guide Reference - -For general writing style and guidelines, refer to the following upstream style guides: - -- [Google Developer Style Guide (Preferred)](https://developers.google.com/style/) -- [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) - -## Style Preferences Modifications - -While adhering to the upstream style guides, observe the following modifications: - -- Use active voice wherever possible to improve clarity and engagement. -- Keep sentences concise and to the point, avoiding jargon unless necessary. - -## Overview - -The Overview section provides a summary of the project and general information for users or contributors. It should include: - -- **Repository information**: Include the link to the GitHub repository and a brief description of the project. -- **Tech stack**: List the technologies used to build the project (e.g., Python, Django, Jekyll, JavaScript). - -## Code of Conduct - -The Code of Conduct section ensures that all contributors are aware of community standards and acceptable behavior. It should include: - -- A brief statement referring to the project's code of conduct. -- A link to the full [CODE_OF_CONDUCT.md](https://github.com/creativecommons/.github/blob/main/CODE_OF_CONDUCT.md) file in the repository. -- Information on how to report issues or violations. - -## Contributing - -The Contributing section provides details for those who wish to contribute to the project, ensuring they follow the right process. Include: - -- A link to the [contribution guideline](https://opensource.creativecommons.org/contributing-code/) file in the repository. -- GitHub Pull Request (PR) guidelines. -- [Repository guideline](https://opensource.creativecommons.org/contributing-code/github-repo-guidelines/). - -## Installation - -The Installation section guides users through setting up the project locally: - -- A list of prerequisites. -- Detailed step-by-step instructions for installing the necessary dependencies and tools. -- Instructions on how to clone the repository and set up the environment. - -## Development - -Provide detailed instructions for contributors on how to run and develop the project locally: - -- Instructions on how to start the local development environment. -- Steps for running the project and viewing changes. -- Any necessary setup (e.g., database, environment variables). - -## Deployment - -The Deployment section includes the steps needed to deploy the application: - -- Deployment prerequisites (if any). -- Step-by-step instructions for deploying the project to the production environment. -- Configuration details for cloud services or hosting providers (e.g., GitHub Pages, AWS). - - -**Note**: Use code block markup for instructions on installation, deployment, and development, especially to write code commands. - -## Terminology - -Establishing a clear "Terminology" section for Creative Commons (CC)-specific usage is crucial. Below are some proprietary terms and their usage: - -- **Creative Commons (CC)**: A non-profit organization enabling sharing and reuse of creative works. -- **Licenses**: Legal tools that allow creators to specify how their works can be used. -- **Attribution**: Giving credit to the creator of a work, required in many CC licenses. From c7b001194563dbf3e21bc6420d2cc818e39d5b4d Mon Sep 17 00:00:00 2001 From: Joy A Date: Thu, 10 Oct 2024 10:50:15 +0100 Subject: [PATCH 5/6] Removed unnecessary folder --- content/blog/authors/Dev-JoyA/contents.lr | 10 ---------- 1 file changed, 10 deletions(-) delete mode 100644 content/blog/authors/Dev-JoyA/contents.lr diff --git a/content/blog/authors/Dev-JoyA/contents.lr b/content/blog/authors/Dev-JoyA/contents.lr deleted file mode 100644 index 2e8423c6..00000000 --- a/content/blog/authors/Dev-JoyA/contents.lr +++ /dev/null @@ -1,10 +0,0 @@ -username: Dev-JoyA ---- -name: Joy Aruku ---- -md5_hashed_email: ---- -about: -Joy Aruku is a MERN stack web developer based in Lagos, Nigeria. - - From ffa4416be610a10224b021fe423186f0a4adc3a4 Mon Sep 17 00:00:00 2001 From: Timid Robot Zehta Date: Thu, 10 Oct 2024 08:21:38 -0700 Subject: [PATCH 6/6] add Lektor headers and theme navigation --- .../documentation-guidelines/contents.lr | 51 ++++++++++--------- themes/vocabulary_theme/templates/layout.html | 1 + .../templates/page-with-toc.html | 2 + 3 files changed, 30 insertions(+), 24 deletions(-) diff --git a/content/contributing-code/documentation-guidelines/contents.lr b/content/contributing-code/documentation-guidelines/contents.lr index 04531a4c..f5efc80a 100644 --- a/content/contributing-code/documentation-guidelines/contents.lr +++ b/content/contributing-code/documentation-guidelines/contents.lr @@ -1,40 +1,43 @@ +_model: page +--- +_template: page-with-toc.html +--- title: Documentation Guidelines +--- description: This Documentation Guidelines (style guide) ensures all the files in all repositories and any other documentation are properly documented. - --- -# Documentation Guidelines +body: -The purpose of this guideline is to provide a step-by-step framework for writing and maintaining high-quality documentation for Creative Commons (CC) projects. This guide covers essential sections such as project style guide Preference, Style modification, terminologies, markdown usage. Following these guidelines ensures consistency, clarity, and ease of use for all contributors and users. - - ## Style Guide Reference +# Documentation guidelines - For general writing style and guidelines, refer to the following upstream style guides: +The purpose of this guideline is to provide a step-by-step framework for writing and maintaining high-quality documentation for Creative Commons (CC) projects. This guide covers essential sections such as project style guide Preference, Style modification, terminologies, markdown usage. Following these guidelines ensures consistency, clarity, and ease of use for all contributors and users. - - [Google Developer Style Guide (Preferred)](https://developers.google.com/style/) - - [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) +## Style guide reference - ## Style Preferences Modifications +For general writing style and guidelines, refer to the following upstream style guides: - While adhering to the upstream style guides, observe the following modifications: - - All acronyms must be defined on first use - - Use active voice wherever possible to improve clarity and engagement. - - Keep sentences concise and to the point, avoiding jargon unless necessary. +- [Google Developer Style Guide (Preferred)](https://developers.google.com/style/) +- [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) +## Style preferences modifications - ## Terminology +While adhering to the upstream style guides, observe the following modifications: +- All acronyms must be defined on first use +- Use active voice wherever possible to improve clarity and engagement. +- Keep sentences concise and to the point, avoiding jargon unless necessary. - Establishing a clear "Terminology" section for Creative Commons (CC)-specific usage is crucial. Below are some proprietary terms and their usage: - - **Creative Commons (CC)**: A non-profit organization enabling sharing and reuse of creative works. - - **Licenses**: Legal tools that allow creators to specify how their works can be used. - - **Attribution**: Giving credit to the creator of a work, required in many CC licenses. +## Terminology +Establishing a clear "Terminology" section for Creative Commons (CC)-specific usage is crucial. Below are some proprietary terms and their usage: +- **Creative Commons (CC)**: A non-profit organization enabling sharing and reuse of creative works. +- **Licenses**: Legal tools that allow creators to specify how their works can be used. +- **Attribution**: Giving credit to the creator of a work, required by most CC licenses. - - ### Markdown Usage - This section provides guidelines for using Markdown in documentation: - - For comprehensive documentation on GitHub-flavored Markdown, refer to the [GitHub Markdown Guide](https://docs.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax). - - For additional information on the specific Markdown implementation used in Lektor, visit the [Lektor Markdown Documentation](https://www.getlektor.com/docs/content/#markdown). - - Note: Use code block markup for instructions on installation, deployment, and development, especially to write code commands. - \ No newline at end of file +## Markdown usage +This section provides guidelines for using Markdown in documentation: +- For comprehensive documentation on GitHub-flavored Markdown, refer to the [GitHub Markdown Guide](https://docs.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax). +- For additional information on the specific Markdown implementation used in Lektor, visit the [Lektor Markdown Documentation](https://www.getlektor.com/docs/content/#markdown). +- Note: Use code block markup for instructions on installation, deployment, and development, especially to write code commands. diff --git a/themes/vocabulary_theme/templates/layout.html b/themes/vocabulary_theme/templates/layout.html index 286a408e..3568c192 100644 --- a/themes/vocabulary_theme/templates/layout.html +++ b/themes/vocabulary_theme/templates/layout.html @@ -79,6 +79,7 @@ ['/contributing-code/github-repo-guidelines', 'GitHub Repo Guidelines'], ['/contributing-code/repo-labels', 'Repository Labels'], ['/contributing-code/foundational-tech', 'Foundational technologies'], + ['/contributing-code/documentation-guidelines', 'Documentation Guidelines'], ['/contributing-code/javascript-guidelines', 'JavaScript Guidelines'], ['/contributing-code/python-guidelines', 'Python Guidelines'], ['/contributing-code/translation-guide', 'Translation Guide'], diff --git a/themes/vocabulary_theme/templates/page-with-toc.html b/themes/vocabulary_theme/templates/page-with-toc.html index de66e351..b9145d67 100644 --- a/themes/vocabulary_theme/templates/page-with-toc.html +++ b/themes/vocabulary_theme/templates/page-with-toc.html @@ -30,9 +30,11 @@

{{ this.title }}

{% if (href == '/contributing-code') %}
    {% for href, title in [ + ['/contributing-code/foundational-tech', 'Foundational technologies'], ['/contributing-code/pr-guidelines', 'Pull Request Guidelines'], ['/contributing-code/github-repo-guidelines', 'GitHub Repo Guidelines'], ['/contributing-code/repo-labels', 'Repository Labels'], + ['/contributing-code/documentation-guidelines', 'Documentation Guidelines'], ['/contributing-code/javascript-guidelines', 'JavaScript Guidelines'], ['/contributing-code/python-guidelines', 'Python Guidelines'], ['/contributing-code/translation-guide', 'Translation Guide'],