If you are interested in supporting or contributing to this guide, please keep on reading.
If you are not, feel free to skip to the next page.
We are currently still in the early phases of this guide, so any form of contribution, including just giving feedback, is greatly appreciated. Please open an issue on our Github repository with your feedback, or begin working on a Pull Request. You can start editing any page by clicking on the EDIT THIS PAGE button in the top bar.
If you are mainly looking for things to work on, refer to the TODO section.
The language of this guide is English. American or British English are both acceptable and there is no preference for either.
The only exceptions are pages specific to a particular language, for example with references to online dictionaries or official grammar rule books, or other typographic advices, for example concerning the usage of quotation marks.
When adding such a page, please briefly describe in your Pull Request what the text is about, what topics it covers, and, if necessary, why it only applies to a specific language.
Documentation for gitbook's toolchain (including gitbook markdown sytax) can be found here: https://toolchain.gitbook.com/
In order to build and preview the guide locally, you need npm and node.js. The former is usually bundled with installation packages for node. Once you have those installed, run the following commands from the repository's folder:
$ npm install added 611 packages from 674 contributors in 4.478s $ ./node_modules/.bin/gitbook install info: installing 5 plugins using [email protected] … $ ./node_modules/.bin/gitbook serve --open Live reload server started on port: 35729 Press CTRL+C to quit ... info: 12 plugins are installed info: loading plugin "highlight"... OK … info: found 11 pages info: found 21 asset files … info: >> generation finished with success in 1.6s ! Starting server ... Serving book on http://localhost:4000
Afterwards, your browser will have opened
with a preview of your files.
Any changes you make to the source
will cause your browser to be refreshed
and automatically reloaded.
Various sections are still under construction.
You will occasionally find
TODO as verbatim text
or within comments.
Our goal is to have a section with one or more pages for each of the roles specified in the roles page.
Feel free to work on any of the
or create a new section.
Currently, we aim to add the following topics in no particular priority:
- Encoding [I'm sure there's something to be done]
- Quality Check
- Karaoke Effects
There is a collection of links here that can be used as reference when working on any future section.
The following are the style guidelines for various aspects of this guide. The most important aspect is having Semantic Linefeeds. The other points may serve as guidelines for formatting future pages. Refer to gitbook's markdown documentation for guidelines on visual formatting.
Always use Semantic Linefeeds when editing text. They are used to break lines into logical units rather than after a certain line length threshold is reached!
They drastically improve sentence parsing in the human brain and make code diffing much more simple compared to hard-wrapping at 80 columns. You should still aim not to exceed 80 columns in a single line, but unless you are writing code or URLs, you will most likely not have any problems with this. Markdown will collapse adjacent lines into a paragraph, so you don't have to worry about the rendered result.
As a rule of thumb, always start a new line on a comma, a period, any other sentence terminating punctuation, parenthesized sentences (not words), or new items in a long list (such as the one you are reading right now).
The indent size is two spaces.
Unordered list lines should be indented once,
while ordered lists are indented twice.
The text of an unordered item should have one space after the
while the text of an ordered item
should start four columns after the number.
- This is an unordered list - With a sublist - And another item in that sublist
1. This is an ordered list. Consecutive lines are indented with four spaces. 2. Another list item … 10. Now only one space after the item number.
All block lists should be separated from text with a blank line on each side. The same applies to code blocks.
Separate headings from text with two blank lines before the heading, and one after. Headings immediately following their parent heading only need one blank line in-between.
Separate text from end-of-section hyperlink lists with one blank line before the list. See below for more information.
There are three types of hyperlinks.
- The text you want highlighted is more than one word,
or different than the shorthand name of the link.
[website's great article][short]
- website's great article
- The text you want highlighted is the same as the shorthand.
- You want the full address displayed.
For the first two hyperlinking styles, you will want to include a line at the end of that header section in the following format.
If there are multiple links used in the first two styles, you will want multiple lines at the end of the header section.
[short1]: [short2]: …
If you are linking to a section on the same page,
[section name](#header) is allowed in-line.
An example of this is the hyperlink section you are reading.
In markdown, this is simply
[the hyperlink section you are reading](#Hyperlinking).
For relative links (links to other pages, images, or files within this repository), follow the guidelines for Jekyll Relative Links.
If you are archiving another website's text or copying their images into this repository, make sure to cite your sources using APA formatting. To generate APA citations, use Citation Machine. Only use this if you fear the website is not a permanent source.
For mid-document citations, use "in-text citations" with footnotes for the full citations. For a full document citation, simply place the full citation at the bottom of the document, under a horizontal rule.