search

Dasharo / dasharo-issues

The Dasharo issue tracker
https://dasharo.com/
25 stars 0 forks source link

Make DTS documentation more user friendly #337

Open TomaszAIR opened 1 year ago

TomaszAIR commented 1 year ago

The documentation for DTS provides lots of stuff like

Some of them are definitely not user friendly as using it needs some technical knowledge.

What we would like to achieve is to create docs by following principals similar to ones, described in Diataxis[1].

We could logically divide docs that are for users, developers, technicians etc.

[1] https://diataxis.fr/

sulewskiprzemyslaw commented 1 year ago

Issue mentioned in the latest DTS PR: https://github.com/Dasharo/docs/pull/369#discussion_r1111618509

TomaszAIR commented 1 year ago

As part of this task, we should carefully review the documentation and make sure that the usability part (downloading DTS, using it, deploying Dasharo, etc.) is described in a clear way, understandable to anyone who wants to try Dasharo. For example, commands like grep, wget, cd should be described in detail, in case they are read by someone who has never dealt with Linux or the terminal.

macpijan commented 1 year ago

As long as we require users to use commands such as grep or wget to update their firmware, it will never be user-friendly.

Teaching the Linux shell commands in documentation is not a good path forward.