I wanted to let everyone know of my intentions to an apply for GSoD 2019 as an technical writer. As you I’m sure you already know, I’m very interested in Hardened Debian for first time Linux users. The first thing I want to do is dispel a few incorrect assumptions that seem to be circulating about this project.
- This project is not a watered down version of Hardened Debian. While this documentation is focused on first time Linux users I plan on keeping the educational areas on pages separate from the core documentation. In essence, Hardened Debian can be thought of as two separate projects rolled into one. Keep in mind this documentation must be kept separate from the current Whonix docs. Why? Confusing Hardened Debian for Whonix could be a distaste for someone who requires anonymity.
The first thing that must be completed is the Core documentation. For the most part, this will be like the Whonix core documentation. There will be a few differences.
Core documentation will include:
Note: there will be no learning areas in the core documentation! There will only be navigation aids to learning areas along with the required knowledge for the specific tutorial. Oh, and a few small “tip” templates here and there.)
- Overview for first time users
- Hardware requirements
- Design and goals
- Features and advantages
- Download, verify, and installation
- First steps
- Troubleshooting (known issues)
- What core documentation do would you like to see included for this GSoD project?
Next is documentation for educating new Linux users so they can stand on their own two feet when using Linux:
Teaching new Linux users is not about writing a few
man pages and calling it an educational area. The only way users will learn is by immersing them in ClI right from the start. However, @onion_knight night was right when he/she said this has been done thousands and thousands of time before. So lets do something different. (Something that will actually work).
man pages: Why should we have a man page section in our documentation? New users know absolutely nothing about terminals/Cli. If the information they need isn’t easy to find or accessible they will end up opening a support request without even trying to find an solution.
This section will document commonly used commands and practical command syntax. Each
man will give a brief outline of the command, how to use it along with practical examples. It takes a while for users to remember the commands they have to use for different tasks. Through repetition they will remember how to use each one over time.
Problem solving: Capable/experienced Linux users have good problem solving skills that they acquire over time. When a problem arises they automatically start searching for a solution, and keep searching until they find an answer or all possible resources have been exhausted. When a new Linux user encounters a problem they automatically open a support request. So, its vital that we encourage – through well written documentation and forum policy – good practices from the very beginning.
Practical problem solving: This will be a tutorial based on troubleshooting best practices. Similar to the Free support principle but this is detailed step by step instructions.
Monitoring log files: Location of system logs (what each one is used for) and commands needed to narrow down the Cli output. (journalctl, dmesg etc…)
systemd: status, starting and stopping services.
Troubleshooting: Connection issues, broken software packages etc.
What would you like to see included in the educational section?
Very detailed guidelines will be written for bug and/or issues reporting. Keep in mind this will be different from https://whonix.org/wiki/FAQ#Reporting_Guidelines. This will be similar to https://www.qubes-os.org/doc/reporting-bugs/ (Simple human friendly language but very detailed).
To make it easier for the community members providing forum support, templates will be made which can be used when community members do not follow forum best practices.
- Duplicate topic: Please follow the guidelines before creating new threads. (with link to forum best practices)
- Off topic: Please follow the guidleines when when contributing to forum discussions. (with link to forum best practices)
Bear in mind that my commitment to the Hardened Debian doc does not end at the completion of GSoD. I plan on maintaining/enhancing the documentation afterwards. So we can afford to try some experimenting with in areas such as formatting and writing style. If the docs need to be changes after the project ends, I’m more than happy to do that.
Feedback is very much appreciated!