Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(trg1.01): add more detailed information about importance of the readme file #530

Merged
merged 13 commits into from
Jan 10, 2024
+26 −11
Merged

docs(trg1.01): add more detailed information about importance of the readme file #530

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
9ff22e1
docs: add more detailed information about importance of the readme file
FaGru3n Dec 6, 2023
f606a4c
docs: modify lowercase's
FaGru3n Dec 6, 2023
c8d6f5a
docs: remove credibility
FaGru3n Dec 6, 2023
9496d1b
docs: rewrite contribution reference
FaGru3n Dec 6, 2023
1683f17
docs: rewrite usage examples
FaGru3n Dec 6, 2023
069389e
chore: update DEPENDENCIES file
FaGru3n Dec 6, 2023
24f215a
docs: rewrite contribution reference
FaGru3n Dec 6, 2023
9ccd6fd
docs: modify leading repo reference for readme + splitting the readme…
FaGru3n Dec 6, 2023
4090379
docs: implement proposals
FaGru3n Dec 6, 2023
50c7c79
docs: licence information
FaGru3n Dec 6, 2023
c66d474
docs: modify common answers
FaGru3n Dec 6, 2023
de0ab53
docs: optimize wording
FaGru3n Dec 12, 2023
cde0086
docs: rephrase docs folder for readme
FaGru3n Dec 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions DEPENDENCIES
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -606,7 +606,7 @@ npm/npmjs/-/on-headers/1.0.2, MIT, approved, clearlydefined
npm/npmjs/-/once/1.4.0, ISC, approved, clearlydefined
npm/npmjs/-/onetime/5.1.2, MIT, approved, clearlydefined
npm/npmjs/-/open/8.4.0, MIT, approved, #7102
npm/npmjs/-/opener/1.5.2, MIT OR WTFPL OR (MIT AND WTFPL), approved, clearlydefined
npm/npmjs/-/opener/1.5.2, MIT AND WTFPL AND WTFPL, approved, #11619
npm/npmjs/-/p-cancelable/1.1.0, MIT, approved, clearlydefined
npm/npmjs/-/p-limit/2.3.0, MIT, approved, clearlydefined
npm/npmjs/-/p-limit/3.1.0, MIT, approved, clearlydefined
Expand Down Expand Up @@ -728,7 +728,6 @@ npm/npmjs/-/react-json-view/1.21.3, MIT, approved, clearlydefined
npm/npmjs/-/react-lifecycles-compat/3.0.4, MIT, approved, clearlydefined
npm/npmjs/-/react-live/3.1.1, MIT, approved, clearlydefined
npm/npmjs/-/react-loadable-ssr-addon-v5-slorber/1.0.1, MIT, approved, clearlydefined
npm/npmjs/-/react-loadable/5.5.2, MIT, approved, #6650
npm/npmjs/-/react-magic-dropzone/1.0.1, MIT, approved, #6622
npm/npmjs/-/react-markdown/8.0.5, MIT, approved, #6635
npm/npmjs/-/react-modal/3.16.1, MIT, approved, clearlydefined
Expand Down
34 changes: 25 additions & 9 deletions docs/release/trg-1/trg-1-1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,37 @@
title: TRG 1.01 - README.md
---

| Status | Created | Post-History |
|--------|--------------|--------------|
| Active | 07-Mar-2023 | |
| Draft | 13-Sept-2022 | |
| Status | Created | Post-History |
|--------|--------------|------------------------------------------|
| Update | 06-Dec-2023 | add detailed information for README file |
| Active | 07-Mar-2023 | |
| Draft | 13-Sept-2022 | |

## Why

A good `README.md` file is the starting point for everyone opening a repository. It should help them find all critical information in an easy way.
A good `README.md` file is the starting point for everyone opening your repository. It should help them find all critical information in an easy way.
A well-maintained `README.md` shows the high level of professionalism of the project. It demonstrates that the developers care about user experience and want to make it easy for others to understand and use their work.

## Description

Each repository **must** contain a `README.md` file which **shall** cover following topics:

- Basic description of repository and its content
- Installation instructions to get component working
- If required, additional post installation configuration steps to finish installation
- Basic documentation of the repository, its content and its structure
- Installation instructions
- If required necessary step(s) to finish the installation
- Usage examples and intended use of your product
- License information
- Troubleshooting and FAQs to help users solve common problems
- Reference your Contribution guideline in the `CONTRIBUTING.md` file
- Contact information to help users getting in touch with you
- Badges to show the status of your project (e.g. build status, code coverage, [etc](https://github.com/badges/shields/blob/master/README.md).)

If installation instructions are too comprehensive for `README.md` move content to `INSTALL.md` file, see [TRG 1.2](trg-1-2.md).
Best practices:

- If installation instructions for your product are too complex being part of `README.md` move its content to a separate `INSTALL.md` file, see [TRG 1.02](trg-1-2.md).
- If your project is too complex to be described in a single `README.md` file, it may be beneficial to relocate specific sections to a dedicated `docs/` folder.
- If your project has multiple component repositories (e.g. frontend and backend), link the other repositories in your leading repository in your `README.md` mutually.

In summary, a good README is a crucial component of any repository, serving as a gateway for users and contributors to understand, use, and potentially contribute to your project. It's a fundamental part of effective project communication and collaboration.

Further [example](https://www.makeareadme.com/) on how to create your `README.md` file.