diff options
| -rw-r--r-- | doc/tissue.skb | 23 |
1 files changed, 22 insertions, 1 deletions
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 |