Skip to content

Commit 89c4b02

Browse files
committed
Removed technical docs guideline from templates to content/contributing code , added markdown to documentaion guideline
1 parent b31cc46 commit 89c4b02

File tree

3 files changed

+91
-99
lines changed

3 files changed

+91
-99
lines changed
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
title: Documentation Guidelines
2+
3+
4+
- ### Markdown Usage
5+
This section provides guidelines for using Markdown in documentation:
6+
- 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).
7+
- For additional information on the specific Markdown implementation used in Lektor, visit the [Lektor Markdown Documentation](https://www.getlektor.com/docs/content/#markdown).
8+
- Note: Use code block markup for instructions on installation, deployment, and development, especially to write code commands.
9+
10+
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
title: Technical Documentation Guidelines
2+
description: This Technical Documentation Guidelines (style guide) ensures all the README files in all repositories and any other technical documentation are properly documented.
3+
4+
---
5+
# Technical Documentation Guidelines
6+
7+
This Technical Documentation Guidelines (style guide) ensures all the README files in all repositories and any other technical documentation are properly documented.
8+
9+
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.
10+
11+
## Style Guide Reference
12+
13+
For general writing style and guidelines, refer to the following upstream style guides:
14+
15+
- [Google Developer Style Guide (Preferred)](https://developers.google.com/style/)
16+
- [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
17+
18+
## Style Preferences Modifications
19+
20+
While adhering to the upstream style guides, observe the following modifications:
21+
22+
- Use active voice wherever possible to improve clarity and engagement.
23+
- Keep sentences concise and to the point, avoiding jargon unless necessary.
24+
25+
## Overview
26+
27+
The Overview section provides a summary of the project and general information for users or contributors. It should include:
28+
29+
- **Repository information**: Include the link to the GitHub repository and a brief description of the project.
30+
- **Tech stack**: List the technologies used to build the project (e.g., Python, Django, Jekyll, JavaScript).
31+
32+
## Code of Conduct
33+
34+
The Code of Conduct section ensures that all contributors are aware of community standards and acceptable behavior. It should include:
35+
36+
- A brief statement referring to the project's code of conduct.
37+
- A link to the full [CODE_OF_CONDUCT.md](https://github.com/creativecommons/.github/blob/main/CODE_OF_CONDUCT.md) file in the repository.
38+
- Information on how to report issues or violations.
39+
40+
## Contributing
41+
42+
The Contributing section provides details for those who wish to contribute to the project, ensuring they follow the right process. Include:
43+
44+
- A link to the [contribution guideline](https://opensource.creativecommons.org/contributing-code/) file in the repository.
45+
- GitHub Pull Request (PR) guidelines.
46+
- [Repository guideline](https://opensource.creativecommons.org/contributing-code/github-repo-guidelines/).
47+
48+
## Installation
49+
50+
The Installation section guides users through setting up the project locally:
51+
52+
- A list of prerequisites.
53+
- Detailed step-by-step instructions for installing the necessary dependencies and tools.
54+
- Instructions on how to clone the repository and set up the environment.
55+
56+
## Development
57+
58+
Provide detailed instructions for contributors on how to run and develop the project locally:
59+
60+
- Instructions on how to start the local development environment.
61+
- Steps for running the project and viewing changes.
62+
- Any necessary setup (e.g., database, environment variables).
63+
64+
## Deployment
65+
66+
The Deployment section includes the steps needed to deploy the application:
67+
68+
- Deployment prerequisites (if any).
69+
- Step-by-step instructions for deploying the project to the production environment.
70+
- Configuration details for cloud services or hosting providers (e.g., GitHub Pages, AWS).
71+
72+
73+
**Note**: Use code block markup for instructions on installation, deployment, and development, especially to write code commands.
74+
75+
## Terminology
76+
77+
Establishing a clear "Terminology" section for Creative Commons (CC)-specific usage is crucial. Below are some proprietary terms and their usage:
78+
79+
- **Creative Commons (CC)**: A non-profit organization enabling sharing and reuse of creative works.
80+
- **Licenses**: Legal tools that allow creators to specify how their works can be used.
81+
- **Attribution**: Giving credit to the creator of a work, required in many CC licenses.

themes/vocabulary_theme/templates/technical-docs-guide.html

-99
This file was deleted.

0 commit comments

Comments
 (0)