Merge pull request #39 from OS2offdig/25-make-a-new-step-by-step-guide-for-new-users-of-the-template

zorp · web-flow · commit a504ce8a2027 · 2024-12-04T19:33:27.000+01:00
25 make a new step by step guide for new users of the template
diff --git a/MAINTAINERS.md b/MAINTAINERS.md
@@ -0,0 +1,39 @@
+# Maintainers
+
+This document provides information about the maintainers of the project, their roles, and how to engage with them.
+
+## Current Maintainers
+
+| Name            | GitHub Username      | Role/Responsibilities                   | Contact Method          |
+|-----------------|----------------------|-----------------------------------------|-------------------------|
+| [Maintainer 1]  | [@username1](https://github.com/username1) | [Role/Responsibility]                  | [email@example.com]     |
+| [Maintainer 2]  | [@username2](https://github.com/username2) | [Role/Responsibility]                  | [email@example.com]     |
+| [Maintainer 3]  | [@username3](https://github.com/username3) | [Role/Responsibility]                  | [email@example.com]     |
+
+## Emeritus Maintainers
+
+| Name            | GitHub Username      | Role/Responsibilities                   | Contact Method          |
+|-----------------|----------------------|-----------------------------------------|-------------------------|
+| [Emeritus 1]    | [@emeritus1](https://github.com/emeritus1) | [Previous Role/Responsibility]         | [email@example.com]     |
+
+## Becoming a Maintainer
+
+To become a maintainer of this project, please follow these steps:
+
+1. **Contribute**: Actively contribute to the project by submitting pull requests and participating in discussions.
+2. **Engagement**: Engage with the community and maintainers through issues and discussions.
+3. **Request**: Once you feel ready, request maintainer status by opening an issue or contacting an existing maintainer.
+
+## Removal Process
+
+Maintainers may be removed or moved to emeritus status under the following circumstances:
+
+- Inactivity for an extended period (e.g., 6 months).
+- Failure to respond to issues or pull requests.
+- Request for removal by the maintainer.
+
+Maintainers can be removed through a consensus among current maintainers.
+
+---
+
+*For any questions or concerns regarding maintainership, please reach out to any of the current maintainers listed above.*
diff --git a/PROJECT_CONTRIBUTING_TEMPLATE.md b/PROJECT_CONTRIBUTING_TEMPLATE.md
@@ -0,0 +1,23 @@
+# Contributing to OS2 Documentation
+
+Contributors to the documentation can be project managers, technical editors, developers, and end-users.  We welcome all contributions that help improve our documentation.
+
+To ensure our documentation stays resilient and up-to-date, we employ the use of the open practice of [Docs As Code](https://openpracticelibrary.com/practice/docs-as-code/) and the open [Markdown](https://en.wikipedia.org/wiki/Markdown) format for ease of collaboration and quality control.
+
+To promote digital sovereignty, interoperability, reuse, transparency and resillience, we adhere to the [Standard for Public Code](https://standard.publiccode.net/), a framework maintained by the [Foundation for Public Code](https://publiccode.net/who-we-are/).
+`<br>`
+`<br>`
+
+## 🚀 Quick start
+
+1. Start by writing a README following the simple criteria in the above guides from Standard for Public Code. For at fast and simple way to accomplish this, you can fill out the placeholders in the PROJECT_README_TEMPLATE.md and [rename it](https://docs.github.com/en/repositories/working-with-files/managing-files/renaming-a-file) to README.md, replacing the Quick start guide for this template with your projects information.
+2. Follow the criteria from [Document the Code](https://standard.publiccode.net/criteria/document-the-code.html), [Document your codebase objectives](https://standard.publiccode.net/criteria/document-codebase-objectives.html) and [Document codebase Maturity]()
+   in one or several text documents using the Markdown format.
+3. Document further suggestions and improvements by [raising issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) and describing what needs to be fixed, describe the user stories and potential delivered values.
+4. Participate in issue discussions to help reach the correct resolutions. If you have the required knowledge about a part of the project, suggest yourself as an [assignee to the issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users#about-issue-and-pull-request-assignees).
+5. Collaborate on documentation branches with issues assigned to you by the maintainers.
+
+> 📚 Read more about:
+>
+> How to use [Markdown](https://www.writethedocs.org/guide/writing/markdown/) to collaborate on documentation
+> How [Just the Docs](https://just-the-docs.github.io/just-the-docs/) is used to generate a documentation site from your markdown files.
diff --git a/README.md b/README.md
@@ -1,42 +1,41 @@
-# Documentation template for OS2 projects
+> [!IMPORTANT] 
+> *Remove this section from your README.md after completing all setup tasks!*
+> - [ ] Click the green "Use this template" button above.
+> - [ ] Name your new repository and create it.
+> - [ ] Replace all the grey placeholder texts with your project-specific information.
+> - [ ] Add any additional relevant Markdown documents to your documentation.
+> - [ ] Configure a [publishing source for GitHub Pages](https://help.github.com/en/articles/configuring-a-publishing-source-for-github-pages).
+> - [ ] **Remove this setup section from your README.md.**
+>
+> *That's it! You are now set up, and your documentation site is live!*
 
-## 🏗️ Getting started 
 
-This is a *bare-minimum* template to create a [Jekyll][Jekyll] site that:
+# [Replace with Project Title]
+> Replace this subtitle section with a clear statement defining the mission and goals of your project in a few simple terms.
 
-- uses the [Just the Docs][Just the Docs] theme;
-- can be built and published on [GitHub Pages][GitHub Pages];
-- can be built and previewed locally, and published on other platforms.
+[How It Works](#🧭-how-it-works) | [Architecture](#architecture) | [ How to Install and Run](#▶️-how-to-install-and-run)
 
-[Browse documentation][Just the Docs] to learn more about how to use this theme.
+## 🧭 How It Works
+> Replace with a brief, clear explanation of how the codebase works to achieve the stated mission objectives.
 
-Documentation in OS2 products must follow the documentation criteria from the [Standard for Public Code](https://standard.publiccode.net/)
+#### Architecture
 
-1. [Document your codebase objectives](https://standard.publiccode.net/criteria/document-codebase-objectives.html)
-2. [Document the Code](https://standard.publiccode.net/criteria/document-the-code.html)
+> Replace with a Brief introduction to the project's high-level architecture. Link to the architecture documentation with a diagram preferably in mermaid syntax.
+[ARCHITECTURE.MD](./docs/ARCHITECTURE.MD)
 
-Following these criteria not only opens up our codebase and fosters collaboration and transparency, but also encourages more organizations to use and adapt our open source products.
+#### Key Features
 
-## Contributing
-Feel free to contribute, suggest an issue or submit a pull request with your improvements to this template.
+> Replace this with a brief explaination of the main features or functionalities of your project.]
 
-## Licensing and Attribution
+## ▶️ How to Install and Run
+> Replace with clear, concise instructions on how to install and run the codebase for development, test and production setups. Link to repositories containing deployment templates that automates deployment
 
-This repository is licensed under the [MIT License][MIT License]. You are generally free to reuse or extend upon this code as you see fit; just include the original copy of the license (which is preserved when you "make a template"). While it's not necessary, we'd love to hear from you if you do use this template, and how we can improve it for future use!
+#### Examples
 
-The deployment GitHub Actions workflow is heavily based on GitHub's mixed-party [starter workflows][starter workflows]. A copy of their MIT License is available in [actions/starter-workflows][actions/starter-workflows].
+> Replace with examples demonstrating key functionality, code-snippets such as command-line usage, API calls or if needed screendumps
 
 ---
 
-[Jekyll]: https://jekyllrb.com
-[Just the Docs]: https://just-the-docs.github.io/just-the-docs/
-[GitHub Pages]: https://docs.github.com/en/pages
-[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/
-[Bundler]: https://bundler.io
-[use this template]: https://github.com/just-the-docs/just-the-docs-template/generate
-[`jekyll-default-layout`]: https://github.com/benbalter/jekyll-default-layout
-[`jekyll-seo-tag`]: https://jekyll.github.io/jekyll-seo-tag
-[MIT License]: https://en.wikipedia.org/wiki/MIT_License
-[starter workflows]: https://github.com/actions/starter-workflows/blob/main/pages/jekyll.yml
-[actions/starter-workflows]: https://github.com/actions/starter-workflows/blob/main/LICENSE
-[^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site).
+*This project is licensed under the terms of the [LICENSE.md](LICENSE.md) | For contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md) | Contact: [maintainer usernames]()*
+
+
