Feature #7224

Link different design documentations from user documentation

Added by BitingBird 2014-05-12 12:29:45 . Updated 2019-04-07 09:23:39 .

Status:
Confirmed
Priority:
Low
Assignee:
Category:
Target version:
Start date:
2014-05-12
Due date:
% Done:

0%

Feature Branch:
Type of work:
Website
Blueprint:

Starter:
0
Affected tool:
Deliverable for:

Description

Some user documentations have basic explanation, while power users might want more details. It would be great if the docomentation pages had links to the design documentation regarding those subjects, ideally in specific CSS. Maybe a “+” icon?

Exemples:

  • MAC Spoofing: doc/first_steps/startup_options/mac_spoofing → contribute/design/MAC_address
  • persistence: doc/first_steps/persistence → contribute/design/persistence
  • unsafe browser: doc/anonymous_internet/unsafe_browser → contribute/design/Unsafe_Browser
  • incremental upgrades (users ask how it can be upgraded without root): upgrade → contribute/design/incremental_upgrades

Subtasks

Related issues

Related to Tails - Feature #7078: Make it clear in MAC spoofing documentation that only the non-vendor bits are randomized? Rejected 2014-04-12
Related to Tails - Feature #7054: Complete MAC spoofing design doc: explain why we only change non-vendor bits Resolved 2014-04-10
Related to Tails - Feature #7038: Randomize full MAC address Rejected 2014-04-07

History

#1 Updated by BitingBird 2014-05-12 12:30:21

  • related to Feature #7078: Make it clear in MAC spoofing documentation that only the non-vendor bits are randomized? added

#2 Updated by BitingBird 2014-05-12 14:40:51

  • Description updated

#3 Updated by sajolida 2014-05-13 04:49:37

We already have a CSS styling for “Next”. Even if we haven’t used it
much, see https://tails.boum.org/download/#installation

But that won’t work for design docs. And I’m afraid the “plus” sign
might be too ambiguous. We need to make clear this link in going into
the internals. Maybe one of those:

/usr/share/icons/gnome/48x48/actions/gnome-run.png
/usr/share/icons/gnome/48x48/actions/add.png

And also, some people we questioning the idea of pointing to the design
docs from the user docs. I don’t think that’s blocking as long as we
make it clear this is hard core reading. Maybe your proposal can help
with that actually.

#4 Updated by intrigeri 2014-06-20 13:19:11

  • Type of work changed from Documentation to Discuss

It doesn’t seem a conclusion was reached, marking as needing discussion.

#5 Updated by emmapeel 2014-10-10 01:47:55

  • related to Feature #7054: Complete MAC spoofing design doc: explain why we only change non-vendor bits added

#6 Updated by emmapeel 2014-10-10 01:48:54

#7 Updated by BitingBird 2016-07-01 14:10:49

  • Status changed from New to Confirmed

#8 Updated by Anonymous 2017-06-30 12:43:19

We seem to have never discussed that. Adding it to the agenda.

#9 Updated by Anonymous 2017-06-30 12:43:55

  • Subject changed from Small block saying "more details" in doc, linking to design to Link to design documentation from user documentation

Proposal initially was: Small block saying “more details” in doc, linking to design

#10 Updated by Anonymous 2017-06-30 12:44:10

  • Subject changed from Link to design documentation from user documentation to Link different design documentations from user documentation

#11 Updated by segfault 2017-10-03 18:29:37

  • Assignee set to intrigeri
  • Type of work changed from Discuss to Research

We discussed this during the October monthly meeting. The following is a summary of that discussion.

Problem description: It happens regularly, that people have questions or doubts about how we implemented what we promise. So we have to manually point them to the design doc. It’s somewhat tiring. And chances are a few other people have the same questions/doubts but don’t ask. We might also be losing potential new contributors there.

The proposed solution is to link from the documentation pages to the appropriate design pages, so that power users can better find those pages on their own. But we worry about the added complexity for 99% of the readers. We hope that a good web designer will find a good solution.

We agree that, to be more welcoming to that web designer, we would like to first propose a few (say, 5-10) design docs to link.

Intrigeri volunteers to create this list of design docs to link. Then we have to wait for someone to do the web design work. The actual implementation could be done by anonym, segfault or u.

#12 Updated by intrigeri 2019-04-07 09:23:39

  • Description updated
  • Assignee deleted (intrigeri)
  • Type of work changed from Research to Website