Contributing
Nice, you have decided that something is missing or should be expanded upon, or perhaps just want to fix a typo. The instructions are written with the expectation that you are at least somewhat familiar with setting up a development environment. If you do not feel up to the task you should try and contact the study board at your division as they should know how to get in touch with the authors.
Request changes
If you have feedback you can file an issue on GitHub. If you have a GitHub account this is an easy process!
To do it you will select New issue on this page and then press Get started on "Feature request". You can then fill out the template, remember to put a descriptive title of what you want and describe why you want it. Here is an example request.
Installation
To set up the development environment, you first of all need mdBook installed.
You should then be able to open the book by running mdbook serve --open in
the project root, which will open the web page and dynamically update as you
edit it.
Contributing
To start editing pages you just have to edit the files in the ´src´ directory. The pages are written in Markdown, if you are unfamiliar with it I recommend reading this.
When you are done, you should open a pull request on the Data101 GitHub page and describe what you have changed. You may then receive feedback on your edit if there is something that has to be changed, it will then be merged with the project and reflected in the actual book!
Editing & Proofreading
Here are some tips for those who are helping test this book. Remember to fill in this Google form as you go. It is totally OK to skip chapters.
- Try all different operating systems
- Try all different education programs (you do not have to test combinations of OS and programs)
- Measure how long time it took to complete a chapter.
- Test links to see if they go to where you expect them to.
- We are mostly interested in what content should be changed, if everyone focuses on spelling mistakes then we would be wasting your time.
- As you go, write down things that were especially good/bad or immediately caught your attention.
When you are done, submit the form
Modifications to mdBook
To better support the flow of the book some modifications have been made. All
modifications in the theme directory can be found by searching for BEGIN DAT101. These additions are custom commands which modify the content in some
way. Some of the custom commands can be escape by prepending them with a
backslash like this \\{{ .windows }}.
Special sections
You can add warning boxes and tasks with [ <section> ]. This can be either
Task, Solution, Danger or Warning. The effect applies to the following
paragraph.
Operating system specific content
To remove unnecessary information for some readers you can apply CSS classes to
hide content for readers not using the specified OS. You can use {{ .<os> }}
to hide the same paragraph and {{ begin .<os> }} and {{ end }} to hide a
larger block of text. See this in action on the Git page. You can also specify
multiple OS:es by separating them with a .. You can use windows, linux or
macos in place of <os>. This is, for example, useful when describing
installation processes.
Program specific content
You can also use the same syntax as above to hide content from other programs.
The possible identifiers are Data, IT and DV.
Keyboard shortcuts
To write keyboard shortcuts, use the !kbd command. For example like this
\!kbd[!ctrl+B]. !ctrl is a special command that can be used within !kbd,
and it gets replaced with Ctrl or ⌘ depending on the operating system the
user chooses.
Inlining icons
You can include icons as well, use \!icon[icon] to display a windows icon.
Any icon from Font Awesome
can be used.
Things to keep in mind
- To remain consistent, use British English.
Deploying
This book is automatically deployed using GitHub Actions. Any change pushed to
the main branch is compiled and uploaded to https://data101.dtek.se.