doc: update design notes on WWW development

[public-inbox.git] / Documentation / design_notes.txt

diff --git a/Documentation/design_notes.txt b/Documentation/design_notes.txt
index 5bb68ce534439ed8aaae92c539d45d23c953efd5..c7a8b26dfe786b8560ecbb3e8e65d82f18c15582 100644 (file)
--- a/Documentation/design_notes.txt
+++ b/Documentation/design_notes.txt
@@ -3,6 +3,7 @@ public-inbox design notes
 
 Challenges to running normal mailing lists
 ------------------------------------------
+
 1) spam
 2) bounce processing of invalid/bad email addresses
 3) processing subscribe/unsubscribe requests
@@ -14,6 +15,7 @@ confused users who cannot unsubscribe.
 
 Use existing infrastructure
 ---------------------------
+
 * public-inbox can coexist with existing mailing lists, any subscriber
   to the existing mailing list can begin delivering messages to
   public-inbox-mda(1)
@@ -34,11 +36,12 @@ Use existing infrastructure
 
 Why email?
 ----------
+
 * Freedom from proprietary services, tools and APIs.  Communicating with
   developers and users of Free Software should not rely on proprietary
   tools or services.
 
-* Existing infrastrucuture, tools, and user familarity.
+* Existing infrastructure, tools, and user familiarity.
   There is already a large variety of tools, clients, and email providers
   available.  There are also many resources for users to run their own
   SMTP server on a domain they control.
@@ -64,17 +67,19 @@ Why email?
 
 Why git?
 --------
+
 * git is distributed and robust while being both fast and
   space-efficient with text data.  NNTP was considered, but does not
   support delta-compression and places no guarantees on data/transport
-  integrity.  However, an NNTP gateway (read-only?) is possible.
+  integrity.  However, a read-only NNTP gateway is implemented.
 
-* As of 2014, git is widely used and known to nearly all Free Software
+* As of 2016, git is widely used and known to nearly all Free Software
   developers.  For non-developers it is packaged for all major GNU/Linux
   and *BSD distributions.  NNTP is not as widely-used nowadays.
 
 Why perl 5?
 -----------
+
 * Perl 5 is widely available on modern *nix systems with good a history
   of backwards and forward compatibility.
 
@@ -83,6 +88,7 @@ Why perl 5?
 
 Laziness
 --------
+
 * Stick to dependencies available in Debian main, this should make it
   easier for potential users to install, and easier for distro
   maintainers to pick up.
@@ -110,6 +116,7 @@ Laziness
 
 Web notes
 ---------
+
 * Getting users to install/run ssoma (or any new tool) is difficult.
   The web views must be easily read/cache/mirror-able.
 
@@ -119,11 +126,12 @@ Web notes
 * Expose Message-ID in web views to encourage replies from drive-by
   contributors.
 
-* Raw text endpoint allows users to write client-side JS endpoints
+* Raw text endpoint allows users to write client-side endpoints
   without hosting the data themselves (or on a different server).
 
 What sucks about public-inbox
 -----------------------------
+
 * Lack of push notification.  On the other hand, feeds seem popular.
 
 * some (mostly GUI) mail clients cannot set In-Reply-To headers
@@ -131,18 +139,20 @@ What sucks about public-inbox
 
 Scalability notes
 -----------------
+
 Even with shallow clone, storing the history of large/busy mailing lists
 may place much burden on subscribers and servers.  However, having a
 single (or few) refs representing the entire history of a list is good
-for small lists since it's easier to lookup a message by Message-ID, so
+for small lists since it's easier to look up a message by Message-ID, so
 we want to avoid splitting refs with independent histories.
 
-ssoma will likely grow its own builtin ref rotation system based on
+ssoma will likely grow its own built-in ref rotation system based on
 message count (not rotating at fixed time intervals).  This would
 split the histories and require O(n) lookup time based on Message-ID,
 where `n' is the number of history splits.
 
 Copyright
 ---------
-Copyright 2013-2015, all contributors <meta@public-inbox.org>
+
+Copyright 2013-2015 all contributors <meta@public-inbox.org>
 License: AGPLv3 or later <http://www.gnu.org/licenses/agpl-3.0.txt>