Skip to content

abbyenredes/Readme-kit

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

14 Commits
README.md
README.md
 
 

Repository files navigation

Hello word! a mi plantilla de documentación

Esto esta hecho para ayudarte a crear un readme atractivo que llame la atención de posibles propuestas ya sea laborales o colaborativas. Preparate para aprender todos mis secretos 😜, y sobretodo preparate a documentar tus proyectos (será tu mickey-herramienta secreta) de una manera divertida.

Qué te vas a encontrar

Kit básico

Vamos a dividir nuestra documentación como si de una página web se tratase:

Tipos de títulos

Te voy a enseñar 2 formas de hacer títulos y subtitulos

markdown-style

Título

subtítulo 1

subtítulo 2

subtítulo 3

# Título
## subtítulo 1
### subtítulo 2
#### subtítulo 3

HTML-style

Título

subtítulo 1

subtítulo 2

subtítulo 3

párrafo

<h1>Título</h1>
<h2>subtítulo 1</h2>
<h3>subtítulo 2</h3>
<h4>subtítulo 3</h4>
<p>párrafo</p>

Tipos de letra

Siguiendo la linea de las letras vamos con los tipos de letras que podemos emplear:

Negrita

**Negrita**

Cursiva

*cursiva*

cursiva negrita

***cursiva negrita***

Centrar un título

Título:

Proyecto readme-kit

si lo queremos centrado:

Proyecto readme-kit

Tipos de índice

Estándar

Versión contraida

¿Que voy a encontrarme?
  1. Acerca del proyecto
  2. Empecemos
  3. Pongamoslo a prueba
  4. Roadmap

Hídrido

Note

Te aconsejo usar el híbrido cuando tu documentación se bastante extensa.

Acerca del proyecto

Aquí me gusta describir de que va mi proyecto, escribir esta parte es fundamental ya que es el gancho para que se siga leyendo tu proyecto. Procura realizar una descripción enganchante, como buena experta en marketing te puedo recomendar el formato AIDA:

Atención

Interes

Deseo

Acción

¿Harto de lidiar con documentación desordenada? Con esta plantilla, crearás documentación clara y sencilla sin esfuerzo. Ahorra tiempo, evita frustraciones y deja que tu código hable por sí mismo. Pruébala, adáptala a tu estilo y disfruta de la tranquilidad de saber que todo está en su lugar. ¡Es tu oportunidad de hacer que tu documentación realmente cuente!

Estado del proyecto

🚧 Proyecto en construcción 🚧

✅ Proyecto finalizdo ✅

Mis herramientas

Aquí me gusta poner mi bibliografía y enlaces utiles, para mi es importante dar reconocimiento a los creadores de contenido y páginas web con información valiosa, aparte que si tengo que ayudar a un compi mejor si tengo el link de esa info a mano.

Empecemos

Checklist

En esta sección suelo poner la laundry list para que el proyecto se pueda realizar, en este caso sería:

  • Recopilar los patrones de mis anteriores documentaciones.
  • Ver como puedo crear una plantilla efectiva.
  • Encontrar un nombre divertido para esta carpeta.
  • Recopilar las páginas que siempre consulto a la hora de realizar mi readme.

Mi paso a paso

Aquí viene la parte más importante en la que ayudandome de texto y contenido visual (imagen, video, grafícos...), documento mi proyecto. Pero antes siempre me gusta poner un disclaimer por si la información quedase obsoleta o haya algún error (estoy abierta a correcciones, así que si ves que en mi contenido hay algo erroneo no dudes en pedirme un fork o contactarme)

Warning

Todo lo escrito es en base a mi experiencia, cada quien tiene su propio camino y tiempo. Espero que lo tomes como un complemento a tu formación y no como las sagradas escrituras.

Ya que estamos suelo usar este tipo de cuadros de texto así que vamos a ponerlos:

Note

Lo uso para poner algún enlace de una información concreta.

Tip

Lo uso para destacar un truco que te facilitará la vida.

Important

Para destacar información importante.

Caution

Resalto algún cambio de versión o si solo funciona para x sistema operativo.

Imagenes

Depende si la imagen esta llena de información o solo un apoyo visual, elijo ponerla entera o si no dejarla en la parte derecha.

Aquí un ejemplo:

Diagrama

imagen importante

Texto plano con una imagen

Documentar tu código trae múltiples beneficios. Facilita la comprensión del propósito y funcionamiento del código, permitiendo a otros desarrolladores y a ti mismo entenderlo rápidamente. Mejora la integración de nuevos miembros en el proyecto, simplificando su adaptación y reduciendo el tiempo de aprendizaje. Además, facilita la evolución del código a medida que el proyecto crece, haciendo que las actualizaciones y expansiones sean más manejables. La documentación también acelera la depuración, ya que proporciona una referencia clara para identificar y corregir errores. Finalmente, asegura que el conocimiento sobre el proyecto se conserve a lo largo del tiempo, incluso con cambios en el equipo.

texto dinámico

Ventajas de Documentar tu Código 📘

  • Claridad Instantánea: Facilita la comprensión del propósito y funcionamiento del código.

  • Integración Rápida: Permite que nuevos desarrolladores se integren rápidamente al proyecto.

  • Evolución Simplificada: Facilita la adaptación y expansión del código a medida que el proyecto crece.

  • Depuración Eficiente: Acelera la identificación y corrección de errores.

  • Valor Duradero: Asegura que el conocimiento del proyecto perdure más allá de los cambios en el equipo.

Tablas

Otro de mis recursos favoritos para poder ver el contenido de un solo vistazo son las tablas, lo use bastante en mi primer proyecto libft y aquí te enseñaré a sacarle partido:

Función Descripción
función 1 Esta función te ayuda a ...
Función 2 Con esta función podras ...

Note

Normalmente suelo usar tablas de 2 columnas pero si lo necesitas puedes usar de más.

Código

Aquí me gusta sobretodo compartir los comandos que uso para que sea de facil acceso:

mkdir 07_minishell

También se puede compartir código entero, pero ya que lo subes en un archivo propio me parece demasiado, a no ser que necesites explicar algo sobre ese código que no se pueda comentar en el mismo. Ejemplo:

#include <libft.h>
int main() {
  ft_printf("Hello, World!");
   return 0;
}

Pongamoslo a prueba

Esta sección la uso sobretodo para poner videos cortos poniendo a prueba mi proyecto:

Vídeos

Tip

personalmente uso windows (aunque soy fan de linux), con la combinación de estas teclas: alt + windows + s accedo a capturar pantalla, allí esta también la opción de capturar video. Luego edito la velocidad en canva para por último convertirlo en gif y subirlo aquí

Aquí te mostraré un ejemplo de como creo una nueva carpeta y la preparo para realizar mi documentación, para mi es importante agregar el archivo README.md para agregar mi documentación y una carpeta llamada img para añadir el contenido visual sin sobrecargar el proyecto, esto es para que quede lo mas limpio posible.

Roadmap

Esta sección es ideal para compartir pseudocódigo ya sea en forma de imagenes (escaneo de tus apuntes), también puedes realizar diagramas de flujo gracias a mermaid:

graph TB
    A[Start] ==> B{Is it?};
    B -->|Yes| C[OK];
    C --> D[Rethink];
    D -.-> B;
    B ---->|No| E[End];
Loading

Note

Te dejo este github donde recopila distintos diagramas con mermaid

Finalmente me gusta despedirme con algun gif cute

Aquí no acaba esto

Así es, esto no acaba porque nos queda lo más importante, compartir la plantilla definitiva para crear un buen readme:

# Titulo

Índice:

- [Acerca del proyecto](#Acerca-del-proyecto)
  - [Estado del proyecto](#Estado-del-proyecto)
  - [Mis herramientas](#Mis-herramientas)
- [Empecemos](#Empecemos)
  - [Checklist](#Checklist)
  - [Mi paso a paso](#Mi-paso-a-paso)
- [Pongamoslo a prueba](#Pongamoslo-a-prueba)
- [Roadmap](#Roadmap)
---
  Versión contraida
<details>
  <summary>¿Que voy a encontrarme?</summary>
  <ol>
    <li>
      <a href="#Acerca-del-proyecto">Acerca del proyecto</a>
      <ul>
        <li><a href="#estado-del-proyecto">Estado del proyecto</a></li>
        <li><a href="#Mis-herramientas">Mis herramientas</a></li>
      </ul>
    </li>
    <li>
      <a href="#Empecemos">Empecemos</a>
      <ul>
        <li><a href="#Checklist">Checklist</a></li>
        <li><a href="#Mi-paso-a-paso">Mi paso a paso</a></li>
      </ul>
    </li>
    <li><a href="#Pongamoslo-a-prueba">Pongamoslo a prueba</a></li>
    <li><a href="#roadmap">Roadmap</a></li>
  </ol>
</details>

## Acerca del proyecto

> esto
> es
> una
> caja

### Estado del proyecto
:construction: Proyecto en construcción :construction:

**:white_check_mark: Proyecto finalizdo :white_check_mark:**

### Mis herramientas
* descripción: [name](link)
* descripción: [name](link)
* descripción: [name](link)

## Empecemos

### Checklist

- [X] Tarea completa.
- [ ] Tarea pendiente.

### Mi paso a paso

> [!WARNING]
> 
> Todo lo escrito es en base a mi experiencia, cada quien tiene su propio camino y tiempo. Espero que lo tomes como un complemento a tu formación y no como las sagradas escrituras.

#### tipos de cuadros de texto:

> [!NOTE]
>
> Lo uso para poner algún enlace de una información concreta.

> [!TIP]
>
> Lo uso para destacar un truco que te facilitará la vida.

> [!IMPORTANT]
>
> Para destacar información importante.

> [!CAUTION]
>
> Resalto algún cambio de versión o si solo funciona para x sistema operativo.

---
### Imagenes

**Diágrama**
![Descripción](link)

**Imagen centrada**
<table>
  <tr>
    <td>
<img height="450" src="link" align="center">
    </td>
  </tr>
</table>

**imagen + texto plano**
<table>
  <tr>
    <td>
<p> 
<img height="200" src="link" align="right">texto.</p>
    </td>
  </tr>
</table>

**Imagen + texto dinamico**

<div>
	<h2 align="left">Titulo</h2>
		<!--  (img) -->
	<div>
		<div style="flex: 1; min-width: 150px;">
		<img height="250" src="link-imagen" style="max-width: 100%; border-radius: 50%; object-fit: cover;" align="right"/>
	</div>
		<!-- doc (text) -->
	<div style="min-width: 150px; ">
		<p>
	texto
</p>
	</div>
  </div>
</div>

---

### Tablas

| Función | Descripción |
| ------------- | ------------- |
| [f1](link)  | -  |
| [F2](link)  | - |

---

### Código

`comandos`

	```C <!--  (tipo de lenguaje) -->
	código completo

	```
## Pongamoslo a prueba

![](link)

---

<table>
  <tr>
    <td>
<img height="450" src="link" align="center">
    </td>
  </tr>
</table>

## Roadmap

![](link)

	```mermaid
	graph TB
    	A[Start] ==> B{Is it?};
    	B -->|Yes| C[OK];
    	C --> D[Rethink];
    	D -.-> B;
    	B ---->|No| E[End];
	```
# Good Luck
![](link)

¿Te parece muy largo?

Vamos a resumirlo aun más

Important

Si te ha sido util esta guía regalame una ⭐.

# 

<details>
  <summary>¿Que voy a encontrarme?</summary>
  <ol>
    <li>
      <a href="#Acerca-del-proyecto">Acerca del proyecto</a>
      <ul>
        <li><a href="#estado-del-proyecto">Estado del proyecto</a></li>
        <li><a href="#Mis-herramientas">Mis herramientas</a></li>
      </ul>
    </li>
    <li>
      <a href="#Empecemos">Empecemos</a>
      <ul>
        <li><a href="#Checklist">Checklist</a></li>
        <li><a href="#Mi-paso-a-paso">Mi paso a paso</a></li>
      </ul>
    </li>
    <li><a href="#Pongamoslo-a-prueba">Pongamoslo a prueba</a></li>
    <li><a href="#roadmap">Roadmap</a></li>
  </ol>
</details>

## Acerca del proyecto

### Estado del proyecto

:construction: Proyecto en construcción :construction:

### Mis herramientas
* : []()
* : []()

## Empecemos

### Checklist

- [ ]
- [ ]

### Mi paso a paso

> [!WARNING]
> 
> Todo lo escrito es en base a mi experiencia, cada quien tiene su propio camino y tiempo. Espero que lo tomes como un complemento a tu formación y no como las sagradas escrituras.

## Pongamoslo a prueba

![](link)

## Roadmap

![](link)

# Good Luck
![](link)

Documenta una API:

Ahora te enseñare la estructura que use para documentar una API, si deseas visualizarla visita API-Track_Truck

Nombre de tu API

¿Que voy a encontrarme?
  1. ¿Qué es tu API?
  2. Tecnologías Utilizadas
  3. Instalación y Configuración
  4. Uso de la API
  5. Contribución

¿Qué es tu API?

[Describe que hace tu API]

🌟 Características

✅ característica 1

✅ característica 2

🛠️ Tecnologías Utilizadas

Important

Utiliza badges para hacerlo mas visual te dejo este repositorio que las tiene markdown-badges

  • Backend: Python
  • Base de Datos: Supabase
  • Frontend: JavaScript
  • Entorno Virtual: .env para configuración segura

🚀 Instalación y Configuración

1️⃣ Clonar el repositorio y entrar

git clone https://github.com/tu-API
cd tu-API

2️⃣ Descarga el entorno virtual: [Es importante que pongas los distintos sistemas operativos]

⚠️ linux/mac

python3 -m venv .venv

⚠️ windows

python -m venv .venv

3️⃣ Inicia el entorno virtual:

⚠️ linux/mac

source .venv/bin/activate

⚠️ windows

.venv\Scripts\activate

4️⃣ Descarga las siguientes dependencias:

uv pip install -r requirements.txt

5️⃣ Configura variables de entorno

Crea el archivo .env en la raíz y configura las siguiente variables:

SECRET_KEY="tu_clave_secreta"
DEBUG=True
DATABASE_URL="postgres://usuario:contraseña@localhost:5432/nombre_db"

6️⃣ Accede a nuestra API:

python manage.py runserver

Important

La API estará disponible en http://127.0.0.1:8000/

📌 Uso de la API

Note

Si quieres ver esto de forma más visual visita:

Swagger UI: http://localhost:8000/docs/

docs [Aquí va una imagen o gif]

Redoc UI: http://localhost:8000/redoc/

redoc [Aquí va una imagen o gif]

🔹 Uso 1

[Escribe que es: Registro de usuario]

[Describe que hace: Permite a los usuarios registrarse en la plataforma.]

Endpoint: [¿Que método usa?: POST /users/signin/]

Parámetros requeridos (Formulario o JSON)

{
    "username": "usuario123",
    "password1": "ContraseñaSegura123",
    "password2": "ContraseñaSegura123",
    "email": "usuario@example.com",
    "user_type": "x" 
}

[!NOTE] [Algo puntual que tener encuenta a la hora de usar tu API] Flujo de redirección:

  • Si el usuario se registra como x → Redirige a x:create_x_form

  • Si el usuario se registra como y → Redirige a y:create_y_form

Ejemplo de respuesta (200 OK) ✔️ [Para conocer si esta todo correcto]

{
    "message": "Usuario registrado correctamente",
    "redirect": "/x/create/"
}

Ejemplo de posibles errores: [Para conocer de antemano errores comunes en tu API]

(400 Bad Request) si las contraseñas no coinciden o faltan datos. ❌

Todo es igual hasta que llegamos a esta excepción en caso de que no sea tan intuitivo

[Excepción DELETE]

Borra y del sistema.

Endpoint: DELETE /y/{id}/delete/

Ejemplo de respuesta (204 No Content)

(No retorna contenido)

Posibles errores 404 Not Found si y no existe. ❌

Vistas HTML (Interfaz Web) [Como no retorna nada es una buena práctica describir que pasa aquí]

  1. Crear un y desde formulario URL: create_y_form/int:user_id/ Muestra un formulario para registrar y.
  • Si y se crea correctamente, redirige a home.
  • En caso de error, recarga la página con un mensaje de error.

  1. Dashboard de y URL: /y/{id}/dr-dashboard/ Muestra los detalles de y.

  2. Actualizar y desde formulario URL: /y/{id}/dr-update/ Formulario para actualizar los datos de y.

  • Si la actualización es exitosa, redirige al dashboard de y.
  • Si hay un error, muestra un mensaje en la página.

aqui va un gif de tu html

Note

[Algo relevante sobre esto]

🤝 Contribución

¡Las contribuciones son bienvenidas! Para contribuir:

  1. Haz un fork del repositorio.

  2. Crea una nueva rama:

    git checkout -b feature/nueva-funcionalidad

  3. Realiza tus cambios y haz commit:

git commit -m "Añadir nueva funcionalidad"
  1. Envía un pull request 🚀.

🚀 ¡Gracias por usar tu API! Si tienes preguntas, crea un issue en el repositorio o contáctanos.

Te comparto la plantilla:

# Nombre de tu API
<details>
  <summary>¿Que voy a encontrarme?</summary>
  <ol>
    <li>
      <a href="#¿Qué-es-tu-API?">¿Qué es tu API?</a>
      <ul>
        <li><a href="#Características"> Características</a></li>
      </ul>
    </li>
    <li><a href="#Tecnologías-Utilizadas">Tecnologías Utilizadas</a></li>
    <li><a href="#Instalación-y-Configuración">Instalación y Configuración</a></li>
    <li>
        <a href="#Uso-de-la-API">Uso de la API</a>
    <ul>
        <li><a href="#uso 1">uso 1</a></li>
        <li><a href="#uso 2">uso 2</a></li>
      </ul>
    </li>
     <li><a href="#Contribución">Contribución</a></li>
  </ol>
</details>


## ¿Qué es tu API?


### 🌟 Características

✅ 

✅  

---

## 🛠️ Tecnologías Utilizadas

- **Backend:** ![]()
- **Base de Datos:** ![]()
- **Frontend:** ![]()
- **Entorno Virtual:**  `.env` para configuración segura

---

## 🚀 Instalación y Configuración

### 1️⃣ Clonar el repositorio y entrar

```textplain
git clone https://github.com/tu-API
cd tu-API
```

### 2️⃣ Descarga el entorno virtual:
⚠️ linux/mac
```textplain
python3 -m venv .venv
```
⚠️ windows
```texrplain
python -m venv .venv
```

### 3️⃣ Inicia el entorno virtual:
⚠️ linux/mac
```textplain
source .venv/bin/activate
```
⚠️ windows
```textplain
.venv\Scripts\activate
```

### 4️⃣ Descarga las siguientes dependencias:
```textplain
uv pip install -r requirements.txt
```
### 5️⃣ Configura variables de entorno
Crea el archivo .env en la raíz y configura las siguiente variables:

```textplain
SECRET_KEY="tu_clave_secreta"
DEBUG=True
DATABASE_URL="postgres://usuario:contraseña@localhost:5432/nombre_db"
```
### 6️⃣ Accede a nuestra API:

```textplain
python manage.py runserver
```
> [!IMPORTANT]
> La API estará disponible en [http://127.0.0.1:8000/](http://127.0.0.1:8000/)

## 📌 Uso de la API
---
> [!NOTE]
> Si quieres ver esto de forma más visual visita:
>
> Swagger UI: http://localhost:8000/docs/
> 
> ![docs]() 
> 
> Redoc UI: http://localhost:8000/redoc/
> 
>  ![redoc]()


## 🔹 Uso 1
---
### 

Endpoint: 

Parámetros requeridos (Formulario o JSON)
```json 
{
   
}
```

> [!NOTE] 
> 

Ejemplo de respuesta (` OK`) ✔️ 
```json
{
   
}

```

Ejemplo de posibles errores: 

(` Bad Request`) . ❌

---

## [Excepción DELETE]

Endpoint: 

Ejemplo de respuesta (`204 No Content`)

(No retorna contenido)

Posibles errores `404 Not Found` si y no existe. ❌

---

### Vistas HTML (Interfaz Web)
1. 
URL:

* 
* 
  
2. 
URL:


![aqui va un gif de tu html]()

> [!NOTE]
> 

---

## 🤝 Contribución  

¡Las contribuciones son bienvenidas! Para contribuir:  

1. Haz un fork del repositorio.
   
3. Crea una nueva rama:
    
   ```sh
   git checkout -b feature/nueva-funcionalidad
   ```
   
4. Realiza tus cambios y haz commit:
   
  ```sh
git commit -m "Añadir nueva funcionalidad"
```

4. Envía un pull request 🚀.
   
---
## 🚀 ¡Gracias por usar ! Si tienes preguntas, crea un issue en el repositorio o contáctanos.

También la versión contraida:

# Nombre de tu API
<details>
  <summary>¿Que voy a encontrarme?</summary>
  <ol>
    <li>
      <a href="#¿Qué-es-?">¿Qué es ?</a>
      <ul>
        <li><a href="#Características"> Características</a></li>
      </ul>
    </li>
    <li><a href="#Tecnologías-Utilizadas">Tecnologías Utilizadas</a></li>
    <li><a href="#Instalación-y-Configuración">Instalación y Configuración</a></li>
    <li>
        <a href="#Uso-de-la-API">Uso de la API</a>
    <ul>
        <li><a href="#uso 1">uso 1</a></li>
        <li><a href="#uso 2">uso 2</a></li>
      </ul>
    </li>
     <li><a href="#Contribución">Contribución</a></li>
  </ol>
</details>


## ¿Qué es ?


### 🌟 Características

✅ 

✅  

---

## 🛠️ Tecnologías Utilizadas

- **Backend:** ![]()
- **Base de Datos:** ![]()
- **Frontend:** ![]()
- **Entorno Virtual:**  `.env` para configuración segura

---

## 🚀 Instalación y Configuración

### 1️⃣ Clonar el repositorio y entrar

```textplain
git clone https://github.com/tu-API
cd tu-API
```

### 2️⃣ Descarga el entorno virtual:
⚠️ linux/mac
```textplain
python3 -m venv .venv
```
⚠️ windows
```texrplain
python -m venv .venv
```

### 3️⃣ Inicia el entorno virtual:
⚠️ linux/mac
```textplain
source .venv/bin/activate
```
⚠️ windows
```textplain
.venv\Scripts\activate
```

### 4️⃣ Descarga las siguientes dependencias:
```textplain
uv pip install -r requirements.txt
```
### 5️⃣ Configura variables de entorno
Crea el archivo .env en la raíz y configura las siguiente variables:

```textplain
SECRET_KEY="tu_clave_secreta"
DEBUG=True
DATABASE_URL="postgres://usuario:contraseña@localhost:5432/nombre_db"
```
### 6️⃣ Accede a nuestra API:

```textplain
python manage.py runserver
```
> [!IMPORTANT]
> La API estará disponible en [http://127.0.0.1:8000/](http://127.0.0.1:8000/)

## 📌 Uso de la API
---
> [!NOTE]
> 

## 🔹 
---
### 

Endpoint: 

Parámetros requeridos (Formulario o JSON)
```json 
{
   
}
```

> [!NOTE] 
> 

Ejemplo de respuesta (` OK`) ✔️ 
```json
{
   
}

```

Ejemplo de posibles errores: 

(` Bad Request`) . ❌

---
## 🔹 
---
### 

Endpoint: 

Parámetros requeridos (Formulario o JSON)
```json 
{
   
}
```

> [!NOTE] 
> 

Ejemplo de respuesta (` OK`) ✔️ 
```json
{
   
}

```

Ejemplo de posibles errores: 

(` Bad Request`) . ❌


## 

Endpoint: 

Ejemplo de respuesta (`204 No Content`)

(No retorna contenido)

Posibles errores `404 Not Found` si y no existe. ❌

---

### Vistas HTML (Interfaz Web)
1. 
URL:

* 
* 
  
2. 
URL:


![aqui va un gif de tu html]()

> [!NOTE]
> 

---

## 🤝 Contribución  

¡Las contribuciones son bienvenidas! Para contribuir:  

1. Haz un fork del repositorio.
   
3. Crea una nueva rama:
    
   ```sh
   git checkout -b feature/nueva-funcionalidad
   ```
   
4. Realiza tus cambios y haz commit:
   
  ```sh
git commit -m "Añadir nueva funcionalidad"
```

4. Envía un pull request 🚀.
   
---
## 🚀 ¡Gracias por usar ! Si tienes preguntas, crea un issue en el repositorio o contáctanos.

Ahora si que hemos llegado al final de esta guía, si hubiera cualquier errata, hazmelo saber.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

20 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors