{{Header}}
{{Title|title=
{{project_name_short}} Documentation Introduction
}}
{{#seo:
|description=Introduction, User Expectations, Footnotes and References
|image=Cat-mia-703408640.jpg
}}
[[File:Cat-mia-703408640.jpg|thumb|175px]]
{{intro|
Introduction, User Expectations, Footnotes and References
}}
= Overview =
{{mbox
| type = notice
| image = [[File:Ambox_notice.png|40px|alt=Info]]
| text = Security is not a program, setup, or final destination -- it is actually a continual process, influenced by new knowledge that is constantly gathered. [This aligns with the axiom that [[Basic_Security_Guide_Introduction|"Security is a process, not a product."]]]
}}
Security is a complex problem and there is no easy solution to the many complicated challenges that all users face. The more you know, the safer and more secure you can be. {{project_name_short}} provides extensive [[Documentation|documentation]] for those interested in learning more.
The goal of this documentation is to describe The {{project_name_short}} Secure Operating System in an easy-to-understand and reasonably thorough manner. It is hoped readers will be exposed to a range of new and improved concepts/applications regarding security on the Internet.
Note that all the applications included in {{project_name_short}} are not fully documented. Usually an overview is provided, with further details on {{project_name_short}}-specific configurations that might be necessary. In general, use the documentation as a reference guide for only those features you intend to use.
= Wiki is the Primary Source of Information vs Forums =
The goal of the wiki is to provide an up-to-date source of information. Should that not be possible, at least appropriate notices will be posted on top of the wiki page. In no case users are expected to read long forum threads, find instructions in forum posts on how to perform actions such as installing applications. This is because posts are seldom edited / kept up-to-date due forums being a different medium of information sharing than a wiki. Users are advised to view the wiki as the primary source of information.
The forums are used to ask for clarifications in case wiki instructions are unclear. The goal of forum discussions should be, if possible, on topic and appropriate, eventually an improved wiki page on that topic. Forum posts will likely and inevitable be outdated over time. It's better to check if the related wiki page has been updated meanwhile.
The wiki should always provide better instructions because collaborative editing of the wiki should result in higher quality documentation. Anyone can [[contribute]]. [[Contribute#Documentation|Improve the Documentation / Edit the {{project_name_short}} Wiki]].
{{Anchor|User Expectations - What documentation is and what documentation is not}}
= User Expectations - What Documentation Is and What It Is Not =
The documentation should be regarded as a showcase. It demonstrates what is possible, at least to a certain extent and with some recent developments. There is no attempt, nor is it feasible, to replace upstream documentation.
Documentation should not be perceived as an offer for all-inclusive technical support. Expectations of instant updates or continuous support are unrealistic.
For instance, an author, while exploring how to set up DNSSEC and showcase unbound, dnssec-trigger, created a wiki page on [https://www.kicksecure.com/wiki/DNS_Security DNS Security]. The wiki initially serves as a personal notepad, but is later rewritten for the public's benefit. However, developers are not equipped to debug every possible issue in all conceivable scenarios.
Writing that wiki page did not transform the author into an expert on, or a developer of, the unbound DNS resolver software. Far from it.
Therefore, in case of issues (such as, theoretically, unbound causing a crash dump), the user is kindly asked to apply the [[Self_Support_First_Policy|Self Support First Policy]] and [[Reporting_Bugs#Generic_Bug_Reproduction|Generic Bug Reproduction]].
= {{project_name_short}} Footnotes and References =
Small text and footnotes like 1 are not that crucial. They contain clarifications, information sources, extra notes for people with higher security needs, additional details to dispel doubts (in the case of controversial issues), proof of something, references, links, and so on. Generally speaking, it is unnecessary to read all of the footnote links (particularly for beginners), but it is encouraged.
For further clarification, footnotes are typically used in the following circumstances:
* Developer notepad: Sometimes links are added when references such as related source code are difficult to find (on search engines or otherwise).
* Supporting evidence: Footnotes often provide additional references to support statements in the main documentation, particularly if factual statements are not obvious. This preempts possible future questions from the {{project_name_short}} population and provides greater clarification at the outset.
* Comments for auditors: In various sections footnotes are added to answer potential auditor questions around specific {{project_name_short}} recommendations, chosen security configurations, why alternatives were not implemented, and so on.
* Reducing duplication: To avoid duplicate tickets and discussions, footnotes often link to existing (usability) issues, as well as identical or related discussions to raise the reader's awareness.
* Reducing confusion: Footnotes will sometimes link to additional information sources in an effort to reduce user confusion. For example, a common use case is when a major {{project_name_short}} configuration has changed; legacy users might be confused why a change was implemented if this issue was not referenced. In general this reduces the likelihood of support requests.
* Troubleshooting: Most software is expected to be fully functional with available instructions. However, in corner cases footnotes can provide possible troubleshooting tips and known workarounds.
* Advanced users: To be more user-friendly, documentation is generally focused on the needs of "everyday" users who do not require specialist configurations or functionality. However, footnotes sometimes provide links or instructions for advanced users to undertake more complicated activities. Footnoting in this case reduces potential confusion for the larger {{project_name_short}} population.
* Other non-essential information: For simplicity, footnotes sometimes contain non-essential links, quotes, research articles and similar material for interested readers.
To remove all doubt, novice or intermediate users can generally ignore footnotes unless experiencing difficulties with the particular software, activity or configuration in question. Footnotes are more valuable for those exploring topics in further detail, undertaking advanced configurations, performing development, or seeking answers to specific questions.
= Third Party Documentation =
As a general issue in the Linux distributions ecosystem, meaning an issue [[unspecific|unspecific to {{project_name_short}}]], for many users it will be difficult to take advantage of documentation for other Linux distributions. It might even be confusing. The documentation might be for a different Linux distribution or generic, meaning for not specific Linux distribution.
Some steps suggested in third party documentation might be unnecessary as these are pre-configured for the user already by {{project_name_short}} or Debian, which {{project_name_short}} is based on.
That is not to discourage the user from reading third party documentation as even suggestion chapter [[About#Based_on_Debian|Based on Debian]], [[Support]] and [[Self Support First Policy]].
As far as security related questions are concerned, [[Reporting_Bugs#Support_Request_Policy|support request policy]] applies.
See also:
* [https://forums.whonix.org/t/the-problem-with-security-guides-and-how-we-can-fix-it/8563 The Problem with Security Guides and How We Can Fix It]
* [[Linux_User_Experience_versus_Commercial_Operating_Systems|Linux User Experience versus Commercial Operating Systems]]
= Recommended Reading =
The documentation is lengthy, so newcomers to the {{project_name_short}} platform or those with limited time should first read these sections:
* [[Warning|{{project_name_short}} and Tor Limitations]]
* The [[Download]] section for the relevant platform
* [[Post Install Advice|Post-installation Security Advice]]
If users have more time available, it is suggested to read the [[Documentation]] widely, particularly the Basic Security Guide, Advanced Security Guide, and Computer Security Education sections.
= Final Warning =
The {{project_name_short}} design is intended to offer a technological means to stay secure on the Internet. However, it should be emphasized that staying secure is not simply a technological problem – there is no tool, including {{project_name_short}} and Tor, that magically provides Internet security. It is necessary to change a host of behaviors as well.
It is certainly helpful to have a deep, technical understanding of Internet architecture, [https://www.britannica.com/topic/cryptology cryptology], [https://securityaffairs.co/wordpress/30202/hacking/tor-traffic-analysis-attack.html traffic analysis] techniques, and the applications that are in use; mainly by knowing what not to do. However, users with basic knowledge who proceed cautiously (using common sense) are likely to protect themselves adequately in most cases.
= License =
{{project_name_short}} Introduction wiki page Copyright (C) Amnesia
{{project_name_short}} Introduction wiki page Copyright (C) 2012 - 2024 ENCRYPTED SUPPORT LP
This program comes with ABSOLUTELY NO WARRANTY; for details see the wiki source code.
This is free software, and you are welcome to redistribute it
under certain conditions; see the wiki source code for details.
= Footnotes =
{{reflist|close=1}}
{{Footer}}
[[Category:Documentation]]