|author||Arun Isaac||2023-03-21 22:12:51 +0000|
|committer||Arun Isaac||2023-03-21 22:12:51 +0000|
doc: Describe tissue's non-discussion-orientedness.
* doc/tissue.skb (Introduction)[Why tissue?]: New section.
1 files changed, 22 insertions, 1 deletions
diff --git a/doc/tissue.skb b/doc/tissue.skb
index 8e16518..61ca112 100644
@@ -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]
(p [In this tutorial, we will learn how to create issues for an