Document Kicksecure

Website
9

Hi everyone,

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.

  • Documentation will be formated using a book like structure like Tails OS. See https://tails.boum.org/doc/index.en.html

  • Documentation will be more user friendly. Take a look at both Redirecting… and Introducing the Qubes Admin API | Qubes OS . What do you notice right from the start? This was written as though the writer was talking directly to you. While both Andrew David Wong (the person who wrote and maintains much of the Qubes docs) and Joanna Rrutkowska (Qubes founder) are capable of writing very high level tech documentation, they chose to use simple terminology and give the documentation more humanistic qualities.

    Why write documentation like this? Think about this for now, and I’ll be creating a few polls in the coming days to get some feedback on how you (the community) would like the docs for this project written. For more on this subject; see Aral Balkan: Superheroes & Villains in Design Aral Balkan: Superheroes & Villains in Design on Vimeo)

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
  • FAQs
  • 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.

    • Creating backups

    • 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 Frequently Asked Questions - Whonix ™ FAQ. This will be similar to Redirecting… (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)
  • etc…

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. :slight_smile:

Feedback is very much appreciated!

1 Like