The Self Documenting Concept

From Kicksecure
< Dev

Ideally complex tools should be self-documenting. In an ideal world, no documentation reading should be required from the user. No wrong impressions should be created.

For example, Tor Browser Downloader is an optional usability enhancement, a tool, a Tor Browser Downloader. It downloads Tor Browser, performs digital signature verification and extracts Tor Browser to folder ~/.tb/tor-browser. It however isn't a mandatory requirement to be able to download or use Tor Browser.

The links where files (version files, archive files, digital signatures) are downloaded from should be visible in the console output. This is because if downloading Tor Browser breaks due to upstream link changes, it is easier for both users and developers to see that Tor Browser Downloader is still using the old link locations.

By a tool being transparent about what things are done it is being attempted to to demystify what the tools is actually doing. In other words, making it appear "less magic" to users.

Advanced users no longer need to ask questions such as "Does Tor Browser Downloader perform digital software verification?" because details on the digital software performing process are presented to the user. Other questions which are avoided are for example:

  • Does Tor Browser Downloader download Tor Browser from the original project website or from a third-party website?
  • Which signing key is used to perform digital software verification?
  • What version of Tor Browser is being downloaded by Tor Browser downloader?
  • When was the signature created which was used to perform digital software verification?
  • Did digital software verification actually succeed or failed this failure was just not noticed by Tor Browser Downloader due to a bug?


Unfinished: This wiki is a work in progress. Please do not report broken links until this notice is removed, use Search Engines First and contribute improving this wiki.