From 753689a318b3252f93a49c02575d1bfae4f75baf Mon Sep 17 00:00:00 2001
From: Arun Isaac
Date: Tue, 21 Mar 2023 22:12:51 +0000
Subject: doc: Describe tissue's non-discussion-orientedness.

* doc/tissue.skb (Introduction)[Why tissue?]: New section.
---
 doc/tissue.skb | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/tissue.skb b/doc/tissue.skb
index 8e16518..61ca112 100644
--- a/doc/tissue.skb
+++ b/doc/tissue.skb
@@ -29,7 +29,28 @@ to build a project website and a powerful search interface to search
 through project issues and documentation. The search interface is
 built on the ,(ref :url "https://xapian.org/" :text "Xapian search
 engine library"), and is available both as a command-line program and
-as a web server.]))
+as a web server.])
+    (section :title "Why tissue?"
+      (subsection :title "tissue is not discussion-oriented"
+        (p [tissue moves away from the discussion-oriented style of popular
+issue trackers such as the GitHub issue tracker. It separates the
+discussion of an issue from the documentation of it. You discuss
+somewhere else (say, on a mailing list, on IRC, or even
+face-to-face), and then distill the discussion into a coherent issue
+report that reads cleanly from top to bottom. Too often, the problem
+with discussion-oriented issue trackers like GitHub is that new
+readers of the issue have to follow the whole discussion from start to
+finish and put it all together in their head to understand what's
+going on. This is tiring, and sometimes people simply give up on
+reading issues that have long discussions. It's much better to have a clear
+succinct actionable issue report. This way, the issue tracker is a list of
+clear actionable items rather than a mess of unreproducible issues.]))
+      (subsection :title "tissue allows and encourages rewriting of issues"
+        (p [Discussion-oriented issue trackers force an append-only
+style where updates to the issue are only possible as newly appended
+messages to the discussion. tissue, on the other hand, allows and
+encourages rewriting of issues to keep the overall issue easily
+readable to a newcomer.]))))
   (chapter :title [Tutorial]
            :ident "chapter-tutorial"
     (p [In this tutorial, we will learn how to create issues for an
-- 
cgit v1.2.3