Merge pull request #291 from autocrypt/newcomerentry

Improving Entry page and navigation

doc/_templates/customindex.html

@@ -31,21 +31,22 @@ <h2>Decentralized</h2>
       <div class="body-masthead-copy">
         <h2>Open Standard</h2>
         <p>
-          Autocrypt is an open standard for e-mail encryption.
+          Autocrypt is an open specification for e-mail encryption.
           Under the hood, it uses OpenPGP and other e-mail standards.
         </p>
       </div>
     </div>
   </div>
   <div>
-    <h2>Our Mission</h2>
+    <h2>What is Autocrypt? What is the status?</h2>
     <p>
-      End-to-end encrypted e-mail has been around for decades, but has failed to see wide adoption outside of specialist communities.  Autocrypt aims to provide encryption convenient enough for much wider adoption. Through strengthening the e-mail ecosystem step-by-step, we want to increase user autonomy and privacy for everyone.
+      Autocrypt is a specification which mail application programmers can implement
+      to offer their users convenient end-to-end encryption for e-mail. The first specification
+      was released in December 2017 and a few mail programs already have or are heading 
+      towards Autocrypt-capable releases in spring 2018.  Please join us in implementing
+      and refining "Level 1" and other upcoming specifications. For any further questions
+      or feedback, see our <a href="{{ pathto('contact') }}">Contact Page</a>.
     </p>
-    <p>
-      The Autocrypt effort is driven by a diverse group of mail app developers, hackers and researchers who are willing to take fresh approaches, learn from past mistakes, and collectively aim to increase the overall end-to-end encryption of e-mail in the net.
-    </p>
-    <!-- say something about open standards and open source here or rather in the "try/get it now" app page? -->
   </div>
   <a href="{{ pathto('install') }}" class="primary-action">
     Test it now

doc/_templates/globaltoc.html

@@ -12,14 +12,13 @@
   <div class="subnav">
     <ul>
       <li><a href="{{ pathto('contact') }}">Contact and Events</a></li>
-      <li><a href="{{ pathto('details') }}">What is Autocrypt?</a></li>
       <li>
         <a href="{{ pathto('level1') }}">Level 1 Spec</a>
         <a href="{{ pathto('autocrypt-spec-1.0.0rc1.pdf', 1) }}">[PDF]</a>
       </li>
-      <li><a href="{{ pathto('examples') }}">Example Mail Flows</a></li>
-      <li><a href="{{ pathto('features') }}">Features</a></li>
       <li><a href="{{ pathto('dev-status') }}">Implementation Status</a></li>
+      <li><a href="{{ pathto('examples') }}">Example Mail Flows</a></li>
+      <li><a href="{{ pathto('background') }}">Project Background</a></li>
       <li><a href="{{ pathto('faq') }}">FAQ</a></li>
       <li><a href="{{ pathto('contents') }}">All Docs</a></li>
     </ul>

doc/details.rst → doc/background.rst

@@ -1,6 +1,11 @@
-Introducing Autocrypt: Encrypted E-Mail for Humans
+Background
 ==================================================
 
+.. contents::
+
+Motivation
+----------
+
 **If users ask how they can secure their e-mail the answer
 should be as simple as: use an Autocrypt-enabled mail app!**
 
@@ -19,7 +24,7 @@ convenient encryption that is neither perfect nor as secure as
 traditional e-mail encryption, but is convenient enough for
 much wider adoption.
 
-The social Autocrypt approach
+The Social Autocrypt Approach
 ------------------------------
 
 The Autocrypt project is driven by a diverse group of mail app developers,
@@ -34,7 +39,7 @@ contributions.  See :doc:`contact channels and upcoming events <contact>` on
 how you may talk with us and who "we" are currently.
 
 
-The technical Autocrypt approach
+The Technical Autocrypt Approach
 --------------------------------------
 
 Autocrypt uses regular E-Mail messages between people to piggyback
@@ -53,3 +58,37 @@ If you are interested to learn more or want to help please :doc:`join our channe
 where we meet next <contact>`.
 
 See :doc:`contents` for an index of all docs and discussion results so far.
+
+
+Design Differences To Previous Approaches
+-----------------------------------------
+
+End-to-end encrypted e-mail has been around for decades, but has failed
+to see wide adoption outside of specialist communities, in large part
+because of difficulties with user experience and certification models.
+To better understand how the Autocrypt effort is different
+from previous ones here are some of its features:
+
+- **Protect first against passive data-collecting adversaries**,
+  resist the temptation to early-add complexity which aim to prevent
+  active attacks.  See :rfc:`RFC7435 A New Perspective
+  <7435#section-1.2>` for some motivation of this and the next points.
+
+- **Focus on incremental deployment**, always consider that there
+  will be both Autocrypt-enabled mail apps and traditional plain ones,
+  interacting with each other.
+
+- **Don't ask users anything about keys, ever.** Minimize and
+  usability-test what needs to be decided by users and include
+  resulting UI guidance in the specs. Minimize friction for people
+  using multiple mail apps with their accounts.
+
+- **Go for mail app changes only**, don't require changes from mail
+  providers or don't depend on third party services, allowing fluid
+  development of deployable code and specs. Ensure mail implementors
+  can actually implement and influence the spec.
+
+- **Use decentralized, in-band key discovery.**  Make mail apps
+  tell each other how and when to encrypt to each other. Send this
+  information in a way that is hidden from users of non-autocrypt mail
+  clients to avoid confusing them.

doc/contents.rst

@@ -9,9 +9,9 @@ and contributors, MUA developers and privacy enthusiasts.
      introduction to why Autocrypt exists and why it is trying
      to achieve more e-mail encryption.
 
-:doc:`features`
-     discusses how the Autocrypt efforts is different from past
-     e2e encryption efforts.
+:doc:`background`
+     discusses the motiviation, technical, social and design
+     approaches of Autocrypt.
 
 :doc:`examples`
      Example data flows and MUA state transitions.  This may be the
@@ -44,7 +44,7 @@ and contributors, MUA developers and privacy enthusiasts.
 .. toctree::
    :hidden:
 
-   features
+   background
    contact
    examples
    level1