diff options
| author | Arun Isaac | 2023-03-21 22:12:51 +0000 |
|---|---|---|
| committer | Arun Isaac | 2023-03-21 22:12:51 +0000 |
| commit | 753689a318b3252f93a49c02575d1bfae4f75baf (patch) | |
| tree | 4d4323eae584c760a0dcdceaea5dc8c02e277929 | |
| parent | 274a99aa32d45bbdd769ebb84672765da50acc71 (diff) | |
| download | tissue-753689a318b3252f93a49c02575d1bfae4f75baf.tar.gz tissue-753689a318b3252f93a49c02575d1bfae4f75baf.tar.lz tissue-753689a318b3252f93a49c02575d1bfae4f75baf.zip | |
doc: Describe tissue's non-discussion-orientedness.
* doc/tissue.skb (Introduction)[Why tissue?]: New section.
| -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 |