forked from Disroot/Howto
309 lines
11 KiB
Markdown
309 lines
11 KiB
Markdown
---
|
|
title: How-to Contribute: Style guide
|
|
published: true
|
|
visible: true
|
|
taxonomy:
|
|
category:
|
|
- docs
|
|
page-toc:
|
|
active: true
|
|
---
|
|
|
|
|
|
|
|
This section intends to provide some basic guidelines about how to write a tutorial or a how-to for the **Disroot**'s [How-to Website](https://howto.disroot.org).
|
|
The purpose of it is to help keep a similar structure to all the how-to's, and to make sure that they contain some features that the **Disroot** community (after some debates) think are important to be in the tutorials.
|
|
|
|
As we mentioned in our contribute page [here](/contribute/git/how-to-use-git), we work with Git, Atom text editor and Markdown Markup language as the tools to write them.
|
|
|
|
But if you're not feel comfortable with these tools you can just write a pad, email, etc. We'll take it all :smiley:
|
|
|
|
<a name="Howto_text_content_structure"></a>
|
|
# How-to's text content structure
|
|
|
|
Basically, a how-to should have the following structure:
|
|
|
|
1. **Meta information**
|
|
2. **Content**
|
|
3. **Licensing Information**
|
|
|
|
## Meta Information
|
|
This is the first section of the how-to and goes before any content. By meta information we mean:
|
|
- **Date of last change to the howto**: this allow anyone to know how old the howto is
|
|
- **What version of the software in question it reffers to**: this way everyone can see if it is updated and reffers to the same software versions they're using
|
|
- **Reference to the changelog**
|
|
- **Table of content (TOC)**: an index of all the information a user will find in the howto. The TOC is *automagically* generated by the website when the content is posted.
|
|
- **A warning that the tutorial might not be up to date**
|
|
|
|
All of this can be done by placing a copy of the following paragraph on the top of the tuturial, and ajusting the information accordingly:
|
|
|
|
|```Meta information```|
|
|
|:--:|
|
|
|```This howto was last updated on``` **date here** *(date format could be mm-dd-yy or yyyy-mm-dd, e.g: 01-04-19 or 2019-01-04)* ```and it reffers to:```<br>**Software name: version 00.0.0-0 for GNU/Linux distro:**<br> <!-- edit Software and version of the actual software -->|
|
|
|
|
**NOTE:**```If the howto reffers to an older software version than the provided by``` **Disroot**,```or the one you're using in your device, there could be missing features or small parts of the information that may have changed.```<br> **Disroot's** ```how-to documentation is a community driven procces. We try to keep it as updated as we can.```
|
|
|
|
[Here](/contribute/git/how-to-use-git/en/template.txt) you can find the template.
|
|
|
|
## The how-to content
|
|
|
|
We think that how-to's text content should be kept at the minimum for the clarity and portabilaty sake of it. In the ideal case, just the specific context necessary, the essential steps to do a task and, whenever it's possible, supported by visual aids (screenshots, gifs) showing how a task is being done.
|
|
|
|
The content of a how-to then should meet the following criteria:
|
|
|
|
1. **Use of visual aids (if it's possible) like**:
|
|
- Screen shots
|
|
- Gif / 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/)
|
|
|
|
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.
|
|
|
|
3. **Concise text content**: Write only what is necessary to explain a task or a feature and warn about important things users should know.
|
|
|
|
4. **Avoid long text paragraphs**
|
|
|
|
5. **Use bullet points instead of a big paragraphs when describing several steps or features**
|
|
|
|
<a name="Some_formating_tips"></a>
|
|
# 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.
|
|
|
|
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.
|
|
|
|
## **Titles**
|
|
|
|
The how-to title itself goes in the page header, you can edit it if you use git.
|
|
|
|
As for the different sections titles of a how-to you can compose it in Markdown by using the `#` symbol and a space before the title itself. For example:
|
|
|
|
Writing this...
|
|
>`# Title 1`<br>
|
|
>`## Title 2`<br>
|
|
>`### Title 3`<br>
|
|
>`#### Title 4`<br>
|
|
>`##### Title 5`
|
|
|
|
... it will be displayed as:
|
|
># Title 1
|
|
>## Title 2
|
|
>### Title 3
|
|
>#### Title 4
|
|
>##### Title 5
|
|
|
|
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 / Index of the page. So they can be used to show the different chapters / sections of the howto at the top of the page index.
|
|
|
|
Example:
|
|
|
|
- [Section about how-to do xyz]()
|
|
- [Section about how-to do that]()
|
|
- [Section about how-to do this]()
|
|
|
|
Smaller titles appear as "sub chapters" in the TOC. This could be useful to do something like this:
|
|
|
|
|
|
- [Log in first]()
|
|
- [The menu]()
|
|
- [Navigation]()
|
|
- [Keep scrolling]()
|
|
- [Replying to posts]()
|
|
- [Creating a new topic]()
|
|
- [The interface]()
|
|
- [Inserting pictures and videos]()
|
|
- [Uploading files to your topic]()
|
|
- [Moving files, pictures and videos from one place to another in the message]()
|
|
- [Adding tags to your topic]()
|
|
- [How to mute or watch categories]()
|
|
|
|
|We recommend the using of one `#` for a title and two `##` for a "sub chapter"|
|
|
|--|
|
|
|
|
---
|
|
|
|
## **Bullet Points**
|
|
|
|
Please, use bullet points to list steps or features in a howto.
|
|
|
|
Making bullet points is easy. Writing...<br><br>
|
|
`- something 1`<br>
|
|
`- something 2`
|
|
|
|
... will show this:
|
|
|
|
- something 1
|
|
- something 2
|
|
|
|
---
|
|
|
|
## **Bold**
|
|
|
|
Please, use bold to highlight:<br>
|
|
- Important information
|
|
- Warnings to the user
|
|
- Or a smaller title inside a section that is not necessary to be listed in the TOC.
|
|
|
|
To highlight a word or a line with bold, use two `*` symbol before and after the part it needed.<br> For example, if you write...
|
|
|
|
`**"Something"**`
|
|
|
|
it will be displayed as:
|
|
|
|
**"Something"**
|
|
|
|
---
|
|
|
|
## **Italic**
|
|
|
|
Italic works in a similar way as bold. You can use the `_` symbol or one `*` symbol before and after the word or text section you want to apply the format.<br>
|
|
Examples:<br>
|
|
Writing...<br>
|
|
|
|
`_example_`<br>
|
|
`*example*`
|
|
|
|
... will show this:
|
|
|
|
_example_<br>
|
|
*example*
|
|
|
|
---
|
|
|
|
## **Links**
|
|
|
|
Sometimes we need to insert links to some pages or websites. It can be done this way:
|
|
|
|
Writing `[link to Disroot website](disroot.org)`
|
|
|
|
will be displayed as:
|
|
|
|
[link to Disroot website](disroot.org)
|
|
|
|
|
|
## **Embedding videos / gifs / screenshots in the howto**
|
|
|
|
As we've mentioned, we like images / videos in the tutorials. You can embed them by doing the following:
|
|
|
|
- First: Creating a folder where to put the videos / gifs / images
|
|
- Second: Naming the files by the order in which they will appear troughout the how-to
|
|
|
|
Then create a link with the path to the folder and name of the file in question.<br>
|
|
So if you write...
|
|
|
|
``
|
|
|
|
... you will see this:
|
|
|
|
|
|
|
|
And if you do this:
|
|
|
|
`text before  text after`
|
|
|
|
you'll get this:
|
|
|
|
text before  text after
|
|
|
|
The structure described above also works to embed gifs and .mp4 videos.
|
|
|
|
---
|
|
|
|
## **Code**
|
|
|
|
If you need to show some terminal commands, code lines, instructions or examples like the ones we've been doing through this guide, you can use the **`** symbol before and after the text you want to show.<br>
|
|
For example:<br>
|
|
|
|
This is a command line command: `sudo apt update`
|
|
|
|
#### **Terminologies**
|
|
|
|
To make the tutorials more coherent and easier to be adapted by other groups, we recommend the use of the following criteria:
|
|
|
|
- When writing a how-to, **Disroot**'s name should be refered as: **Disroot**, starting with capital letter and bold type.
|
|
|
|
- And the different services refered as follows:
|
|
|
|
|Service|Disroot name|
|
|
|-:|:-|
|
|
|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**|
|
|
|Nextcloud Contacts App|**Disroot Contacts**|
|
|
|
|
This way, if the expressions are regular, it's easier to just do a "*Search and replace*" :wink:
|
|
|
|
---
|
|
<a name="Licensing_of_text_how-tos"></a>
|
|
# Licensing of text how-to's
|
|
|
|
As we'd stated at the [licensing page](howto.disroot.org/en/licensing), all how-tos in this website are under a [Creative Commons Attribution-ShareAlike license](https://creativecommons.org/licenses/by-sa/4.0/) (CC BY-SA), so we ask anyone who wants to contribute with a howto to license their work under this same licensing. If you have any doubts, please, visit our licensing page.
|
|
|
|
That said, the last part of the howto is the licensing information. It should be at the bottom of the page and looking like this:
|
|
|
|
> ---
|
|
> <center><a rel="license" href="http://creativecommons.org/licenses/by- sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" /></a><br />This work is licensed under a <br><a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.</center>
|
|
|
|
You can do it by pasting the following code at the end of the related howto:
|
|
|
|
```
|
|
---
|
|
|
|
<center><a rel="license" href="http://creativecommons.org/licenses/by- sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" /></a><br />This work is licensed under a <br><a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.</center>
|
|
|
|
---
|
|
```
|
|
|
|
|
|
|
|
---
|
|
<a name="Video_howtos"><a/>
|
|
# Video how-to's
|
|
|
|
For video how-tos we also think that the content should be **kept at the minimum** and **short** enough for the user to be able to complete a task and for the clarity sake of it.
|
|
|
|
Same as the text how-tos, the tutorials should have the folowing structure:
|
|
|
|
1. **Meta Information**
|
|
2. **Content**
|
|
3. **Licensing**
|
|
|
|
**Meta information** and **licensing information** will be place by the **Disroot** admins in the video description of the Peertube instance where the videos will be hosted.
|
|
|
|
## Description of Content
|
|
|
|
To the extent possible, videos should go with:
|
|
|
|
- Title of the how-to
|
|
- Brief description of what it is about
|
|
- Software version it refers to
|
|
|
|
So that they can be placed by **Disroot** admins on the video description at the Peertube instance.
|
|
|
|
## Content
|
|
|
|
## Licensing of video how-to's
|
|
|
|
As we mentioned before, the licensing information will be placed by Disroot's Admins in the video description.
|
|
|
|
However we recommend that you place the following image at the end of your video for about 10 seconds fade in and out:
|
|
|
|
|
|
|
|
In this case if the video is downloaded and reuploaded somewhere else the license information is still there
|
|
|
|
---
|