Project

General

Profile

Feature #7224

Link different design documentations from user documentation

Added by BitingBird over 5 years ago. Updated 8 months ago.

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

0%

Feature Branch:
Type of work:
Website
Blueprint:
Starter:
No
Affected tool:

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_spoofingcontribute/design/MAC_address
  • persistence: doc/first_steps/persistencecontribute/design/persistence
  • unsafe browser: doc/anonymous_internet/unsafe_browsercontribute/design/Unsafe_Browser
  • incremental upgrades (users ask how it can be upgraded without root): upgradecontribute/design/incremental_upgrades

Related issues

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

History

#1 Updated by BitingBird over 5 years ago

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

#2 Updated by BitingBird over 5 years ago

  • Description updated (diff)

#3 Updated by sajolida over 5 years ago

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 over 5 years ago

  • Type of work changed from Documentation to Discuss

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

#5 Updated by emmapeel about 5 years ago

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

#6 Updated by emmapeel about 5 years ago

#7 Updated by BitingBird over 3 years ago

  • Status changed from New to Confirmed

#8 Updated by u over 2 years ago

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

#9 Updated by u over 2 years ago

  • 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 u over 2 years ago

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

#11 Updated by segfault about 2 years ago

  • 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 8 months ago

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

Also available in: Atom PDF