Projecte - Project

On this page

Introduction

README.md

We can describe a README file as a guide that gives users a detailed description of a project you have worked on.

It is essential to know how to document your project by writing a README because:

  • It is the first file a person will see when they encounter your project, so it should be fairly brief but detailed.
  • It will make your project standout from a bunch of others. Also be sure your project is good too.
  • It will help you focus on what your project needs to deliver and how.

While working on a project, keep in mind that you will need other developers to understand your code and what it does. So accompanying it with an extra guide will be really helpful.

A very important thing to note is that there’s not one right way to structure a good README. But there is one very wrong way, and that is to not include a README at all.

What to Include in your README

Project’s Title

This is the name of the project. It describes the whole project in one sentence, and helps people understand what the main goal and aim of the project is.

Project Description

This is an important component of your project that many new developers often overlook.

Your description is an extremely important aspect of your project. A well-crafted description allows you to show off your work to other developers as well as potential employers.

The quality of a README description often differentiates a good project from a bad project. A good one takes advantage of the opportunity to explain and showcase:

  • What your application does,
  • Why you used the technologies you used,
  • Some of the challenges you faced and features you hope to implement in the future.

Table of Contents (Optional)

If your README is very long, you might want to add a table of contents to make it easy for users to navigate to different sections easily. It will make it easier for readers to move around the project with ease.

How to Install and Run the Project

If you are working on a project that a user needs to install or run locally in a machine like a “POS”, you should include the steps required to install your project and also the required dependencies if any.

Provide a step-by-step description of how to get the development environment set and running.

How to Use the Project

Provide instructions and examples so users/contributors can use the project. This will make it easy for them in case they encounter a problem – they will always have a place to reference what is expected.

You can also make use of visual aids by including materials like screenshots to show examples of the running project and also the structure and design principles used in your project.

Also if your project will require authentication like passwords or usernames, this is a good section to include the credentials.

Include Credits

If you worked on the project as a team or an organization, list your collaborators/team members. You should also include links to their GitHub profiles and social media too.

Also, if you followed tutorials or referenced a certain material that might help the user to build that particular project, include links to those here as well.

This is just a way to show your appreciation and also to help others get a first hand copy of the project.

Additional README Sections

Badges

Badges aren’t necessary, but using them is a simple way of letting other developers know that you know what you’re doing.

Having this section can also be helpful to help link to important tools and also show some simple stats about your project like the number of forks, contributors, open issues, etc…

The good thing about this section is that it automatically updates itself.

Don’t know where to get them from? Check out the badges hosted by [shields.io(https://shields.io). They have a ton of badges to help you get started. You may not understand what they all represent now, but you will in time.

How to Contribute to the Project

This mostly will be useful if you are developing an open-source project that you will need other developers to contribute to. You will want to add guidelines to let them know how they can contribute to your project.

Also it is important to make sure that the licence you choose for an open-source projects is correct to avoid future conflicts. And adding contribution guidelines will play a big role.

Some of the most common guidelines include the Contributor Covenant and the [Contributing guide(https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors). These docs will give you the help you need when setting rules for your project.

Include Tests

Go the extra mile and write tests for your application. Then provide code examples and how to run them.

This will help show that you are certain and confident that your project will work without any challenges, which will give other people confidence in it, too

Extra points

Here are a few extra points to note when you’re writing your README:

  • Keep it up to date - It is a good practice to make sure your file is always up to date. In case there are changes make sure to update the file where necessary.

  • Pick a language – We all come from different zones and we all speak different languages. But this does not mean you need to translate your code into vernacular. Writing your README in English will work since English is a globally accepted language. You might want to use a translator tool here if your target audience isn’t familiar with English.

There are many tools which you can also use to automatically generate a README for your project, but it’s always a good practice to try it on your own before moving to automation. In case you want to check them out, they include:

CHANGELOG.md

Un registro de cambios (“changelog”), es un archivo que contiene una lista cronológicamente ordenada de los cambios más destacables para cada versión de un proyecto.

El archivo tiene que llamarse CHANGELOG.md

Para facilitar a los usuarios y colaboradores ver exactamente qué cambios reseñables se han realizado entre cada versión del proyecto.

LICENSE.md

It lets other developers know what they can and cannot do with your project.

We have different types of licenses depending on the kind of project you are working on. Depending on the one you will choose it will determine the contributions your project gets.

The most common one is the GPL License which allows other to make modification to your code and use it for commercial purposes. If you need help choosing a license, use check out this link: https://choosealicense.com/

/docs

Documentation is often never prioritized until last minute. The template aims to revert the malpractice by setting up the documentation as an integral part, inspired by literate programming.

A project docs folder (/docs) is a designated, centralized repository within a project’s root directory used to organize documentation, reducing confusion and improving collaboration.

It typically contains README files, user guides, technical specifications, design documents, and project proposals to maintain structured, version-controlled records.

Keeps project-related documentation separate from source code, scripts, and media files, facilitating easy navigation and maintaining high-quality documentation standards.

Often divided into subfolders like docs/user/ for user documentation and docs/administration/ for technical or admin setup,

/project-root
├── /docs
│   ├── installation.md
│   ├── API-spec.pdf
│   └── /design
├── /src
├── /data
├── /tests
└── README.md

/data

This folder holds all the data utilized in the project. When appropriate, we recommend distinguishing between raw-data, which serves as input for data analysis processes, and derived-datasets, which are outputs generated after analysis. Additionally, within this data folder, we suggest organizing datasets by thematic folders. For example, folders could be named: conflict, admin-boundaries, population, and so forth.

Pending