About page and edit reasons

2 files changed, 28 insertions, 11 deletions

diff --git a/about.gmi b/about.gmi
index 81502c5..6eda11a 100644
--- a/about.gmi
+++ b/about.gmi
@@ -1 +1,5 @@
-About stub!
+# About our issue tracker
+
+We are leaving the github issue tracker in favour of one that is built on git+gemtext. The reasons and conventions are listed at
+
+=> issues/README.gmi
diff --git a/issues/README.gmi b/issues/README.gmi
index 5c7db2c..434bd2f 100644
--- a/issues/README.gmi
+++ b/issues/README.gmi
@@ -2,20 +2,29 @@
 
 Why do we want to consolidate issue trackers and kanban boards using gemini+git? Several reasons:
 
-* Get rid of web service dependencies (in our case github issue tracker and trello kanban)
+* Get rid of external web service dependencies (in our case github issue tracker and trello kanban)
 * Track issues in text files - edit with your favourite editor
 * Provide our own viewer - the github issue tracker and trello boards are not very configurable, e.g. what to do with a stale issue - why do we need to run an action?
+* Clean up history
 * Own the trackers
 
-Now the last one may be the most important. Currently anyone can post on our issue trackers and you get issues like
+Now the last one may be the most important. Currently anyone can post on github issue trackers and you get issues like
 
 => https://github.com/genetics-statistics/GEMMA/issues/250 Not read the docs example
 
-Where someone posts who has not read the manual (sorry for the exposition). Or from another project I am involved in
+Where someone posts who has clearly not bothered read the manual (sorry). Or from another project I am involved in as a maintainer:
 
 => https://github.com/vcflib/vcflib/issues/206 Rude example
 
-where someone is very rude and lacks obvious knowledge about the free software effort (not sorry about exposing this one - luckily this is a small minority). With our new gemini tracker we own the issue reporting space. People can submit a request to report an issue and we can decide whether it belongs there or not. Takes a little more effort on the submitter too! But not too much - you have to know git or fork and clone in github. The downside may be that some normal users feel they need to do too much. In that case send an E-mail instead - that is what they do anyway. We can file E-mails as issues ourselves.
+or from the same person
+
+=> https://github.com/konradjk/loftee/issues/23 Another one
+
+where someone is rude and lacks obvious knowledge about the free software effort (not so sorry about exposing this one --- luckily this concerns a small minority). One glaring problem is that github does not allow removing these controversial tracks. The problem with service providers, such as Microsoft owned github, is that you are bound by *their* rules.
+
+With our new gemini tracker we own the issue reporting space. People can submit a request to report an issue and we can decide whether it belongs there or not. Takes a little more effort on the submitter too! But not too much - you have to know git or edit, fork or clone in github. The downside may be that some normal users feel they need to do too much. In that case one can always send an E-mail to the mailing list instead - or we create a web form that does that. In the next step we can file E-mails as issues ourselves.
+
+Key point is that the issue tracker is to track issues.
 
 ## Example
 
@@ -25,11 +34,11 @@ I added a first issue here:
 
 ## Process
 
-I am thinking we just use git to pull out dates and people contributions (pjotrp wrote ...) for display in a document/web page.
+We leverage git to pull out dates and people contributions (pjotrp wrote ...) for display in a document/web page. This page is generated:
 
-Assuming people add to the doc at the bottom that should not be too hard.
+=> ../tracker.gmi
 
-At the top we could add tags:
+To create the tracker we add tags:
 
 * assigned: pjotrp, zachs
 * keywords: critical bug, in progress
@@ -43,7 +52,7 @@ For the kanban board we can simply use the keywords. Override/add with a separat
 
 * kanban: Brain storm
 
-Keywords are flexible, but common ones are
+Keywords are fairly flexible, but common ones are
 
 * request
 * bug
@@ -62,7 +71,11 @@ Can't think of anything more to add to make it really useful :)
 
 ## Tracking information
 
-Git can do all of that. A viewer may benefit from serial git information, therefore it is recommended to add information to the end of the file.
+Git can do all of that. A viewer may benefit from serial git information, therefore it is recommended to add information at the end of the file. Though, unlike other issue trackers, this is not obligatory. One can insert notes using the '>' prefix
+
+> This is a comment
+
+Or one can simply use git blame to figure out who did what.
 
 ## Closing issues
 
@@ -70,7 +83,7 @@ Moving an issue file will disconnect the git record. Therefore simple add
 
 * closed
 
-## Converting
+## Converting github issues
 
 ### Converting issues from a github issue tracker