H2 Contribute Redux · Part 5: Completed Intro & Git chapters

pages/04.Contribute/01.procedure/docs.en.md

@@ -9,7 +9,6 @@ taxonomy:
     tags:
         - contribute
         - procedure
-        - style
 page-toc:
     active: true
 ---
@@ -17,28 +16,27 @@ page-toc:
 # Howto Procedures: What does it mean?
 The possibility of writing a tutorial and making it accessible to everyone in their own languages is fundamental in order to encourage and promote not only the use of free/libre and open source software but also collective thoughts and actions. So coordinating the amount of information to be written and translated is an important task, therefore we developed a basic set of steps to follow to help us achieve this goal.
 
-The process is rather simple:
+The procedure is rather simple:
 1. We get a copy of the files we are going to work on;
 2. we work locally on the files,
-3. and once we have finished, we submit the work.
+3. and once we have finished, we submit them.
 
 Sounds pretty easy, doesn't it? Well, it really is. Of course, every step of the process has its own set of actions, which we will see later on, but that is it basically.
 
-# What tools do I need?
+# What tools do we need?
 We use three tools for our work: **Git**, **a text editor** and **Gitea**.
 
-We choose **Git** for several reasons, the main one being our documents structure and code language. Even though there are many (and very good ones) translation tools which look more "user friendly", none of them fit our use case or have **Markdown** text format support out-of-the-box. In the best scenario, it will requires us to make massive modifications on the files in order to strip them down into several "text sections" or "strings". Another important reason is that **git** allows us to keep track on the changes made on those files, making it easier to manage and collaborate on them. And one more reason is that **Gitea** (our **Git** hosting software) has a lot of useful features to organize and improve the work in one single place.
+We choose **Git** for several reasons, the main one being our documents structure and code language. Even though there are many (and very good ones) translation tools which look more "user friendly", none of them fit our use case or have **Markdown** text format support out-of-the-box. In the best scenario, it will requires us to make massive modifications on the files in order to strip them down into several "text sections" or "strings". Another important reason is that **Git** allows us to keep track on the changes made on those files, making it easier to manage and collaborate on them. And one more reason is that **Gitea** (the code hosting software we use with **Git**) has a lot of useful features to organize and improve the work in one single place.
 
 OK, let's check our tools:
 
 1. **Git**: If you are a **GNU/Linux** user it is highly probable that you already have it installed (you can check in your software package manager or through the terminal with the command `which git`). If you are using **Microsoft Windows** or **Mac OS**, you can download it from [here](https://git-scm.com/downloads).
 
-2. **A text editor**: Although there are many of them, we suggest you to use one with **Markdown** format support and **Git** integration. Both, **Kate Editor** and **Atom Text Editor**, meet this criteria, and they are also Free/Libre and Open Source multiplatform software. But, **for practical reasons, we will only see how to work in Atom** (in the future we will include other tools).
+2. **A text editor**: Although there are many of them, we suggest you to use one with **Markdown** format support and **Git** integration. **Kate Editor**, **Atom Text Editor** and **VSCodium**, meet this criteria natively, and they are also Free/Libre and Open Source multiplatform software. But, **for practical reasons, we will only see how to work in Atom** (in the future we will include other tools).
 
   **Atom Text Editor**: [Download](https://atom.io/) · [Source code](https://github.com/atom/atom)
 
 
-
 3. **A Disroot Gitea account**: In order to be able to submit your work, you will need to register an account on our **Gitea** instance (**Disroot** credentials will not work) and request access to our repository.
 
   [**Register a new account**](https://git.disroot.org/user/sign_up) on **Disroot's Gitea** instance.

pages/04.Contribute/01.procedure/docs.es.md

@@ -9,36 +9,36 @@ taxonomy:
     tags:
         - contribuir
         - procedimiento
-        - estilo
 page-toc:
     active: true
 ---
 
-# Procedimientos Howto: ¿Qué quiere decir?
-The possibility of writing a tutorial and making it accessible to everyone in their own languages is fundamental in order to encourage and promote not only the use of free/libre and open source software but also collective thoughts and actions. So coordinating the amount of information to be written and translated is an important task, therefore we developed a basic set of steps to follow to help us achieve this goal.
+# Procedimientos Howto: ¿Qué significa?
+La posibilidad de escribir un tutorial y hacerlo accesible para todxs en sus propios idiomas es fundamental no solo para fomentar y promover el uso de software libre y de código abierto sino también pensamientos y acciones colectivas. Así que coordinar la cantidad de información a ser escrita y traducida es una tarea importante, por lo tanto desarrollamos una serie básica de pasos a seguir para que nos ayude a lograrlo.
 
-The process is rather simple:
-1. We get a copy of the files we are going to work on;
-2. we work locally on the files,
-3. and once we have finished, we submit the work.
+El procedimiento es bastante simple:
+1. Obtenemos una copia de los archivos sobre los que vamos a trabajar;
+2. trabajamos localmente en ellos,
+3. y una vez que hemos terminado, los enviamos.
 
-Sounds pretty easy, doesn't it? Well, it really is. Of course, every step of the process has its own set of actions, which we will see later on, but that is it basically.
+Suena bastante fácil, ¿no?. Bueno, realmente lo es. Por supuesto, cada paso del procedimiento  tiene su propio conjunto de acciones, que veremos más adelante, pero es eso básicamente.
 
-# What tools do I need?
-We use three tools for our work: **Git**, **a text editor** and **Gitea**.
+# ¿Qué herramientas necesitamos?
+Usamos tres herramientas para nuestro trabajo: **Git**, **un editor de texto** y **Gitea**.
 
-We choose **Git** for several reasons, the main one being our documents structure and code language. Even though there are many (and very good ones) translation tools which look more "user friendly", none of them fit our use case or have **Markdown** text format support out-of-the-box. In the best scenario, it will requires us to make massive modifications on the files in order to strip them down into several "text sections" or "strings". Another important reason is that **git** allows us to keep track on the changes made on those files, making it easier to manage and collaborate on them. And one more reason is that **Gitea** (our **Git** hosting software) has a lot of useful features to organize and improve the work in one single place.
+Elegimos **Git** por varias razones, la principal es la estructura y el lenguaje de código de nuestros documentos. Aunque hay muchas (y muy buenas) herramientas de traducción que parecen más "fáciles de usar", ninguna de ellas se ajusta a nuestro caso de uso o tienen soporte para el formato de texto **Markdown** por defecto. En el mejor de los escenarios, requeriría que hagamos modificaciones enormes sobre los archivos para poder desglosarlos en muchas "secciones de texto" o "cadenas". Otra razón importante es que **Git** nos permite mantener un registro de los cambios realizados sobre esos archivos, haciéndo más sencillo manejarlos y colaborar sobre ellos. Y una razón más es que **Gitea** (el software para hospedar código que usamos con **Git**) tiene un montón de funcionalidades muy útiles para organizar y mejorar el trabajo en un solo lugar.
 
-OK, let's check our tools:
+Muy bien, repasemos nuestras herramientas:
 
-1. **Git**: If you are a **GNU/Linux** user it is highly probable that you already have it installed (you can check in your software package manager or through the terminal with the command `which git`). If you are using **Microsoft Windows** or **Mac OS**, you can download it from [here](https://git-scm.com/downloads).
+1. **Git**: Si eres usuarix de **GNU/Linux** es altamente probable que ya lo tengas instalado (puedes chequearlo en tu gestor de software o a través de la terminal con el comando `which git`). Si estás usando **Microsoft Windows** o **Mac OS**, puedes descargarlo desde [aquí](https://git-scm.com/downloads).
 
-2. **A text editor**: Although there are many of them, we suggest you to use one with **Markdown** format support and **Git** integration. Both, **Kate Editor** and **Atom Text Editor**, meet this criteria, and they are also Free/Libre and Open Source multiplatform software.
+2. **Un editor de texto**: Aunque hay muchos de ellos, sugerimos utilizar uno con soporte para el formato **Markdown** e integración con **Git**. Los editores **Kate**, **Atom** y **VSCodium**, cumplen con este criterio de forma nativa, y también son programas multiplataforma con licencias libres y de código abierto. Pero, **por razones prácticas, solo veremos cómo trabajar en Atom** (en el futuro incluiremos otras herramientas).
 
-  **Kate Editor**: [Download](https://kate-editor.org/) · [Source code](https://invent.kde.org/utilities/kate)  |  **Atom Text Editor**: [Download](https://atom.io/) · [Source code](https://github.com/atom/atom)
+  **Atom Text Editor**: [Descargar](https://atom.io/) · [Código fuente](https://github.com/atom/atom)
 
-3. **A Disroot Gitea account**: In order to be able to submit your work, you will need to register an account on our **Gitea** instance (**Disroot** credentials will not work) and request access to our repository.
 
-  [**Register a new account**](https://git.disroot.org/user/sign_up) on **Disroot's Gitea** instance.
+3. **Una cuenta de Disroot Gitea**: Para poder enviar tu trabajo, necesitarás registrar una cuenta en nuestra instancia de **Gitea** (las credenciales de **Disroot** no funcionarán) y solicitar acceso a nuestro repositorio.
 
-Once you have these tools, it is time to set them up to start working.
+  [**Registrar una cuenta nueva**](https://git.disroot.org/user/sign_up) en la instancia **Gitea** de **Disroot**.
+
+Una vez que tengas estas herramientas, es momento de configurarlas para comenzar a trabajar.

pages/04.Contribute/02.git/docs.en.md

@@ -16,113 +16,71 @@ page-toc:
 ---
 
 # Git?
-Yes, **Git**. It is a control version system, a software that allows you to track modifications to files, keeping a record of all the changes made, so if you need to revert to a specific version you can do it in a relatively easy way. It is also a powerful collaboration tool, since it allows many people working on the same files of a project.
+Yes, **Git**. It is a control version system, a software that allows us to track modifications to files, keeping a record of all the changes made, so if we need to revert to a specific version we can do it in a relatively easy way. It is also a powerful collaboration tool, since it allows many people working on the same files of a project.
 
 To learn the basics of Git and to work with it can be not only very useful but also a fun experience.
 
 
-# Scope of this tutorial
-Our use of Git does not require a high level of technical knowledge, anyone can learn the set of basic commands needed. And, to make it even easier, there are several text editors with Git integrated to reduce the interaction with the terminal to the minimum.<br>
-To learn the basics of Git and to work with it can be not only a very useful but also a fun experience.
-
-
 # Scope of this tutorial
 Our use of Git doesn't require a high level of technical knowledge, anyone can learn the set of basic commands needed. And, to make it even easier, there are several text editors with Git integrated to reduce the interaction with the terminal to the minimum.<br>
-So the aim of the following tutorial is to introduce you to the basics of Git, the main tool we use to manage the **Howto** project files. Therefore, we will not cover all the aspects of its usage, only some basic concepts and commands.
+So the aim of the following tutorials is to introduce you to the basics of Git, the main tool we use to manage the **Howto** project files. Therefore, we will not cover all the aspects of its usage, only some basic concepts and commands.
 
 If you get more interested about Git, there are lots of in-depth tutorials and documentation written about it that you can easily find on the internet.
 
+
 # What does Git do?: Basic concepts
 
 ![](en/git.png)
 
-
 When you read a **Disroot** tutorial, what you are seeing is the representation in your browser of a piece of code, in our case, a text file written in a formatting syntax called **Markdown**. The entire code of this site and its content is hosted in a **Git repository**, a folder containing all the project files and the changes history of each and every one of those files (what has changed, who has changed it and why it has changed).
 
 In this repository (or repo) there is a **main branch** (or "master branch"), which is the default project line of development and from which different other branches can be created without compromising it.
 
-When a tutorial needs to be modified (e.g., some software has been updated, typos were found in a document, there is information to be added/removed, etc) or translated what we do is copy the remote repository into our machine, this way we can work locally on the files. This procedure is called **cloning** and once it is done, all Git operations are managed from our local repository.
+Think of a tree: the "main branch" would be the trunk from which different branches "grow and develop". Once they complete their cycle, they can be integrated into the "trunk" or even "fall" from it without affecting it.
 
-## Cloning the **Howto Disroot** repository
-As we mentioned before, the process of getting a copy of all the files within the project is called "**to clone**" a repository. And once we have the clone (the copy) of the repo, all modifications will be done on this copy in our local machine (most of the work is done offline).
-
-To clone the repository just open a terminal, navigate to the directory you would like to clone the repository to, and run `git clone <url>` command, where **url** is the address of the repository you want to clone. In our case it would be:
-
-`git clone https://git.disroot.org/Disroot/Howto`
-
-If you want to translate a page from the **Disroot Website** then type:
-
-`git clone https://git.disroot.org/Disroot/Website`
-
-The process will then begin and in a few minutes, depending on our internet connection, we will have the repository "copied" on our machine.
-
-![](en/cloning.png)
-
-Once the repository is cloned to your hard drive you will see a `Howto` (or a `Website`) directory that content all the files of the site. You can later move that directory to any place you want on your computer.
-
-When you read a **Disroot** tutorial, what you are seeing is the representation in your browser of a piece of code, in our case, a text file written in a formatting syntax called **Markdown**. The entire code of this site and its content is hosted in a **git repository**, a folder containing all the project files and the changes history of each and every one of those files (what has changed, who has changed it and why it has changed).
-
-In this repository (or repo) there is a **main branch** (or "master branch"), the default project folder where is the "final" code, the one is online or in "production".
-
-When a tutorial needs to be modified (e.g., some software has been updated, typos were found in a document, there is information to be added/removed, etc) or translated what we do is copy the remote repository into our machine, this way we can work locally on the files. This procedure is called **cloning** and once it is done, all Git operations are managed from our local repository.
-
-Next step will be to create a new **branch**, a fork of the main branch on which we can make modifications without compromising the original code.
+So, the main branch is the one that contains the code we see online (or "in production") and the branches we create are the ones that contain our work.
 
 ![](en/git_branches.png)
 
+This way, when a tutorial needs to be modified (e.g., because some software has been updated, typos were found in a document, there is information to be added/removed, etc) or translated, what we do is copy the remote repository into our machine so we can work locally on the files. This procedure is called **cloning** and once it is done, all modifications and Git operations are managed from our local repository.
 
-But before we really get to work, let's setup our identity so we can move forward without distractions.
+## Cloning the **Howto Disroot** repository
+As we mentioned before, the process of getting a copy of all the files within the project is called "**to clone**" a repository. And once we have cloned it, all modifications will be done on this copy in our local machine (most of the work is done offline).
+
+To clone the repository we just open a terminal, navigate to the directory we would like to clone the repository to, and run the `git clone` command, that is, we "tell" git through this command to "download" it. The command is followed by the **url address** of the repo we want to clone. In our case it would be:
+
+`git clone https://git.disroot.org/Disroot/Howto`
+
+If we want to translate a page from the **Disroot Website** then we type:
+
+`git clone https://git.disroot.org/Disroot/Website`
+
+The process will then begin and in a few minutes, depending on our internet connection, we will have the repository "cloned" on our machine.
+
+![](en/cloning.png)
+
+Once this process has been completed, we will see a `Howto` (or a `Website`) directory containing all the files of the site. We can later move that directory to any place we want on our computer.
+
+Now, before we really get to work, let's setup our identity so we can move forward without distractions.
 
 ## Setting your identity
-In order to be able to send your work from your machine to the remote repository, it is necessary to setup your username and email, this information is used by Git to "sign" your commits (the "snapshots" of your modifications, we will see this later on).
+In order to be able to send our work from our machine to the remote repository, it is necessary to setup our username and email. This information is used by Git to "sign" the commits (the "snapshots" of our modifications, we will see this later on).
 
-1. Open a terminal in (or browse to) a directory/folder where you want to clone the repository. In our example, we will be doing it in a directory called "Disroot" in the home folder.<br>
+1. We open a terminal in (or navigate to) the directory/folder where we have the cloned repository. In our example, we will do it in a directory called "Disroot" in the home folder.<br>
 
 2. Type and complete with your information the following commands:<br>
 `git config --global user.email` **user@email** `<- here goes your email address`<br>
 `git config --global user.name` **"Username"** `<- and here your username`
 
-You will not need to enter this information again.
+We will not need to enter this information again.
 
 ## Requesting access to the Disroot repository
-But before we really get to work, let's setup your **Gitea** account so we can move forward without distractions.
-
-## Setting your Gitea account
-In order to be able to send your work from your machine to the remote repository, it is necessary to setup your **Gitea** username and email and request access to it.
-
-1. Open a terminal and start Git<br>
-`git init`<br>
-
-2. Type and complete with your information the following commands:<br>
-`git config --global user.email` **user@email** `<- here goes your email address`<br>
-`git config --global user.name` **"User Name"** `<- and here your username`
-
-You will not need to enter this information again.
-
 The faster and recommended way to request access is via our **Howto Chat room** at `howto@chat.disroot.org`. You can also send us an email to `howto@disroot.org`.
 
-Once admins grant you the access, you will be able to "*push*" your changes to the server.
+Once admins grant you the access, you will be able to "*push*" (send) your changes to the server.
 
 !! **NOTE**<br>
-!! You can start working without access granted as all the changes happen on your local computer.
-
-
-## Cloning the **Howto Disroot** repository
-Ok, now we need to get a copy of all files within the project onto our local hard drive. This process is called "**to clone**" a repository. And once we have the clone (the copy) of the repo, all modifications will be done on this copy in our local machine (most of the work is done offline).<br>
-When we have decided that the changes (new tutorial, translation) are finished we can sent/sync them back to the repository on the server, this action is called **push**.
-
-
-To clone the repository just open a terminal, navigate to the directory you would like to clone the repository to, and run `git clone <url>` command, where **url** is the address of the repository you want to clone. In our case it would be:
-
-`git clone https://git.disroot.org/disroot/Howto`
-
-If you want to translate a page from the **Disroot Website** then type:
-
-`git clone https://git.disroot.org/disroot/Website`
-
-Once the repository is copied to your hard drive you will see a `Howto` (or a `Website`) directory that content all the files of the site.
-
-You can later move that directory to any place you want on your computer.
+!! You could start working without access granted as all the changes happen on your local computer, and requesting it later.
 
 
 Ok. Now we finally can start to work.