Contribute H2 · Styleguide revision
This commit is contained in:
parent
f7cc4e928c
commit
4e64f68e59
GPG Key ID:
CF5244A128ECB266
|
|
@ -17,7 +17,7 @@ page-toc:
|
|||
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 procedure is rather simple:
|
||||
1. We get a copy of the files we are going to work on;
|
||||
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 them.
|
||||
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ page-toc:
|
|||
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.
|
||||
|
||||
El procedimiento es bastante simple:
|
||||
1. Obtenemos una copia de los archivos sobre los que vamos a trabajar;
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ page-toc:
|
|||
---
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
<a name="behind"></a>
|
||||
## Table of Content
|
||||
- [Our local branch is "behind" the remote main branch](#behind)
|
||||
|
||||
|
|
@ -25,25 +25,25 @@ page-toc:
|
|||
|
||||
<a name="behind"></a>
|
||||
## Our local branch is "behind" the remote main branch
|
||||
While we are working on your branch, other users possibly commit and merge their own changes, especially if we are working on existing files. If those changes from the other users have already been merged to the **main branch**, the version of the files we changed may no longer be the actual ones and therefore the changes from other users may not be included in our files. In that case, if we want to let our changes be merged to the **main branch**, the process could become quite complicated.
|
||||
While we are working on our branch, other users possibly commit and merge their own changes, especially if we are working on existing files. If those changes from the other users have already been merged to the **main branch**, the version of the files we changed may no longer be the actual ones and therefore the changes from other users may not be included in our files. In that case, if we want to let our changes be merged to the **main branch**, the process could become quite complicated.
|
||||
|
||||
We need to update our branch **before** we **request** a **Pull** (a merge request). By doing this we will spare the admins and ourselves a lot of needless work.
|
||||
So we need to integrate the changes made on the remote main branch into our local main one **before** we can **request** a **Pull** (a merge request). By doing this we will spare the admins and ourselves a lot of needless work.
|
||||
|
||||
In Git there are two ways that allow us to integrate/merge/update branches: **git merge** and **git rebase**.
|
||||
|
||||
**Git merge** compares the last two commits of each branch and the "common ancestor" of both branches we want to merge and creates a new commit with the changes.
|
||||
**Git merge** compares the last two commits of each branch and the "common ancestor" of both branches we want to merge and creates a new commit with the changes. When we merge one branch into our own, we merge the history of both branches together. If we then do that again, we will start to create a series of interleaved histories.
|
||||
|
||||
**Git rebase** tracks one by one the commits made on one branch and "replicates" them into other. This is helpful only if we apply it on the local commits that are not "uploaded" to any remote repository. If we do the "rebase" on a local branch which commits were already pushed to the remote one, we will surely have lots of conflicts.
|
||||
**Git rebase** tracks one by one the commits made on one branch and "replicates" them into the other. This means that all our local commits will appear at the end, after the remote commits and we will have a clearer history. That is why this is the preferred method.
|
||||
|
||||
It is important to note that **rebase** is helpful **only** if we apply it on the local commits that have not yet been "uploaded" to any remote repository. If we do the "rebase" on a local branch which commits were already pushed to the remote one, we will surely have a number of conflicts.
|
||||
|
||||
So if we are working on a local branch and we want to integrate to it the changes made to the remote main branch we will need to "rebase".
|
||||
|
||||
To rebase:
|
||||
1. Make sure all the changes are committed (locally)
|
||||
|
||||
Steps to rebase:
|
||||
1. Make sure all the changes are committed on our local branch only.
|
||||
2. In the terminal:
|
||||
- switch to the **Main Branch**: `git checkout master`;
|
||||
- update the **Main Branch**: `git pull`;
|
||||
- switch back to our working branch: `git checkout our.branch`;
|
||||
- update our working branch from the updated **Main Branch**: `git rebase master`.
|
||||
|
||||
3. Finally, verify the changes and commit the changes to the remote repository.
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ To learn the basics of Git and to work with it can be not only very useful but a
|
|||
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 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.
|
||||
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
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ As we can see in the image above, the **pages** directory contains several other
|
|||
|
||||
# Pages
|
||||
There are currently two different templates for the **Howto** pages:
|
||||
- **docs.md**: these are the most common text files we can find in the Howto site, the pages that made the howtos.
|
||||
- **docs.md**: these are the most common text files we can find in the Howto site, the pages that make the howtos.
|
||||
|
||||
- **docsparent.md**: these pages are used to index all the **child pages** that are marked as `indexed:true` in its **headers**, creating a menu of the related pages. If an image is placed in the folder of a *child page*, a thumbnail will be shown in the index (preferred thumbnail size is 400x300).
|
||||
|
||||
|
|
|
|||
|
|
@ -35,10 +35,22 @@ A basic list of the main operating systems we try to cover would be the followin
|
|||
!! **Everyone, no matter the operating system they use, can collaborate by writing how to use a service. Remember that the most important thing is to make the information available to anyone.**
|
||||
|
||||
## Second question: Who are the howtos aimed at?
|
||||
In principle, any person over 16 years of age can use the **Disroot** services. But we can also think about the fact we all have, for example, relatives and acquaintances older that us who we would like to introduce to the use of socially ethical and technically useful tools or maybe they just want to do it by themselves.
|
||||
In principle, any person over 16 years of age can use the **Disroot** services. But we can also think about the fact we all have, for example, relatives and acquaintances who we would like to introduce to the use of socially ethical and technically useful tools or maybe they just want to do it by themselves.
|
||||
|
||||
So when writing a howto we must think that the information must be understandable to anyone, regardless of age or technical knowledge. Of course, there are always software that are more complex than others, but that should not mean that we do not make the effort to try to make it possible for anyone to learn them.
|
||||
|
||||
This leads to the following question.
|
||||
|
||||
## Third question: What type of language should we use?
|
||||
In order to make the howtos as accessible as possible, not only to the users but also to those who help us translate them, we must use English in the least informal way we can. This means avoiding the use of technical jargon, slang or linguistic contractions (for example, it is preferable to write "it will not" instead of "it won't"). We must also keep in mind that these guides could be used or translated by other projects that provide similar services or software and we want the task of adapting them to consume as little of their time as possible.
|
||||
|
||||
In those cases where the use of technical terms is unavoidable, we will need to explain briefly what they mean or refer to an external source (i.e., a Wikipedia article) that does so.
|
||||
|
||||
## Fourth question: Regarding translations, should they be literal?
|
||||
Although there is not a specific and effective method, there are, at least, two important things we should keep in mind when doing a translation.
|
||||
1. **Understand the text of the howto integrally**. Before we start translating, it is advisable to read the entire text and "capture" its essence: "what is it about", "how the information is presented and/or structured", "is it hard/easy to understand", etc. This will help us to identify the context of the words and expressions that appear in a given document and which meaning depends on it.
|
||||
2. **Follow the original text is fundamental as is preserving its fluidity**. Sometimes we could find words or expressions that are really hard to translate into our language or even untranslatable. So we need to be careful not to omit them or change their original meaning too much because this can affect the overall meaning of a line, a paragraph or an entire document. If we have doubts about certain adaptations we can always consult or ask in the Howto chat room.
|
||||
|
||||
So the literalness of a translation does not always result in a coherent text. When it is necessary to make adaptations of expressions or words, these must be as faithful as possible to the original meaning of the document.
|
||||
|
||||
Finally, we will always need to proofread our translations before submitting them. It is very common to find small recurring mistakes or inconsistencies and correcting them in time will prevent a translation from being returned to us.
|
||||
|
|
|
|||
|
|
@ -13,22 +13,27 @@ page-toc:
|
|||
active: true
|
||||
---
|
||||
|
||||
# Content visual guidelines
|
||||
# Visual content guidelines
|
||||
|
||||
The content of a how-to then should meet the following criteria:
|
||||
As with information, when including visual content we must follow some criteria so that a howto is, above all, didactic and useful. Keep in mind that sometimes too many images can make lose focus on the information and result in a rather confusing document. Not to mention that this can unnecessarily increase the loading time of the page.
|
||||
|
||||
1. **Use of visual aids (if it's possible) like**:
|
||||
So the fist thing we need to do is to evaluate which are the basic visual aids that need to be included. For example, to find a menu or a configuration, to describe actions, how to perform them or compare the effects of their execution.
|
||||
|
||||
# General criteria
|
||||
In general terms, the visual content of a howto then should meet the following criteria:
|
||||
|
||||
1. **Use of visual aids** _(whenever possible)_ **like**:
|
||||
- Screen shots
|
||||
- Gif / video recording of the desktop or mobile
|
||||
- GIF images / video recording of the desktop or mobile
|
||||
|
||||
!!
|
||||
!! For gif / video recordings of a desktop we usually work with [**Peek**](https://github.com/phw/peek)
|
||||
!!
|
||||
!! For mobile devices you can use [**screenrecorder**](https://f-droid.org/en/packages/com.orpheusdroid.screenrecorder/)
|
||||
* Recommended software:
|
||||
- [**Peek**](https://github.com/phw/peek): animated GIF recorder (Desktop)
|
||||
- [**ScreenCam**](https://f-droid.org/en/packages/com.orpheusdroid.screenrecorder/): screen recorder (Mobile)
|
||||
- [**scrcpy**](https://github.com/Genymobile/scrcpy): mobile screen recorder (Desktop)
|
||||
|
||||
2. **Easy to adapt by other projects**: In order to do so, we think that mentions to **Disroot** and other unique identifiers of the **Disroot** project, should be kept at the necessary minimum and the content the more generic and adjectiveless as possible. This way, it's easier for other projects to use, adapt and edit the howtos.
|
||||
2. **Easy to adapt by other projects**: In order to do so, mentions to **Disroot** and other unique identifiers of the **Disroot project**, should be kept at the necessary minimum and the content the more generic and adjectiveless as possible. This way, it is easier for other projects to use, adapt and edit the howtos.
|
||||
|
||||
3. **Concise text content**: Write only what is necessary to explain a task or a feature and warn about important things users should know.
|
||||
3. **Concise text content**: Write only what is necessary to explain a task or a feature and warn about important things users should know, for example by using "notices" (see below).
|
||||
|
||||
4. **Avoid long text paragraphs**
|
||||
|
||||
|
|
@ -36,15 +41,18 @@ The content of a how-to then should meet the following criteria:
|
|||
|
||||
6. **Avoid using tables, unless it serves a purpose other then text formating.**
|
||||
|
||||
#### Notes:
|
||||
## Using "Notices":
|
||||
"Notices" are small pieces of text we may use to highlight important information, for example to emphasize something users should keep in mind or be aware of when configuring something or before they perform an action.
|
||||
|
||||
Start line with !! to format notices. Add exclamation mark image with \!\[]\(/home/icons/note.png)
|
||||
To format a notice we need to start the text with two exclamation marks `!!`.
|
||||
|
||||
Example:
|
||||
|
||||
!! 
|
||||
!! **NOTE!** If you lose your password, you won't be able to retrieve your files on the cloud as they're encrypted, so even the server administrators can't see their content.
|
||||
For example:
|
||||
```
|
||||
!! **NOTE!** this an example of an important information.
|
||||
```
|
||||
|
||||
it will look like:
|
||||
!! **NOTE!** this an example of an important information.
|
||||
|
||||
#### Inline images
|
||||
|
||||
|
|
@ -56,11 +64,11 @@ Images are centered by default in the next line. To use an image inline, so on t
|
|||
----------------------------------------------------------------------
|
||||
|
||||
|
||||
# Some formating tips
|
||||
# Markdown: Some formating tips
|
||||
|
||||
**Disroot**'s [How-to Website](https://howto.disroot.org/) is built with [Grav](https://getgrav.org/), and uses **Markdown** as Markup / Formating text composing language because it's an easy one to do so.
|
||||
As we already mentioned, **Disroot**'s [How-to Website](https://howto.disroot.org/) is built with [Grav](https://getgrav.org/), and it uses **Markdown** as markup / formating text composing language because it is lightweight and its syntax is easy to learn.
|
||||
|
||||
So if you want to write a how-to for **Disroot** and you're not experienced with Markdown, here are some tips and recomandations about the text formating of a tutorial.
|
||||
Here below you will find some tips and recommendations about the text formating of a tutorial.
|
||||
|
||||
## Titles
|
||||
|
||||
|
|
@ -88,6 +96,8 @@ The more `#` you use the smaller the title will be.
|
|||
|
||||
Titles are important for several reasons. One of the main is that Grav uses them to automatically generate the TOC (Table of Content) of the page. So they can be used to show the different chapters / sections of the howto at the top of the page index.
|
||||
|
||||
|
||||
|
||||
Smaller titles appear as "sub chapters" in the TOC. This could be useful to do something like this:
|
||||
|
||||
We recommend the using of one `#` for the main page title and two `##` for sub chapters. You can use `###` titles for minor headers within the text, that you want to be in the TOC and even smaller titles for headers that do not need to be in the TOC.
|
||||
|
|
@ -203,13 +213,10 @@ To make the tutorials more coherent and easier to be adapted by other groups, we
|
|||
|Lufi|**Disroot Upload**|
|
||||
|Forum/Discourse|**Disroot Forum**|
|
||||
|Etherpad|**Disroot Pad**|
|
||||
|EtherCalc|**Disroot Calc**|
|
||||
|XMPP|**Disroot Chat**|
|
||||
|Email services in general|**Disroot Email**|
|
||||
|Rainloop|**Disroot Webmail**|
|
||||
|Hubzilla Instance|**DisHub**|
|
||||
|Private Bin|**Disroot Bin**|
|
||||
|Polls|**Disroot Polls**|
|
||||
|Nextcloud:|**Disroot Cloud**|
|
||||
|Nextcloud Calendar App|**Disroot Calendar**|
|
||||
|Nextcloud Notes App|**Disroot Notes**|
|
||||
|
|
|
|||
Loading…
Reference in New Issue