fix: improve the write-up and navigation (#64)

* fix: improve the write-up and navigation

* fix: upgrade module

docs/.vitepress/config.ts

@@ -74,7 +74,11 @@ export default withMermaid(
                   link: '/engineering/development/project-owner',
                 },
                 {
-                  text: 'Show and Tell',
+                  text: 'Linear Guidelines',
+                  link: '/engineering/development/linear-guidelines',
+                },
+                {
+                  text: 'Progress Reviews',
                   link: '/engineering/development/show-and-tell',
                 },
                 {

docs/engineering/development/index.md

@@ -111,4 +111,5 @@ When we build a release (see [Release Management](release-management)), we need
 [Project Owner Role](project-owner) - who is responsible for getting things done
 [Show and Tell](show-and-tell) - sharing details of our work as we go
 [Infrastructure](infrastructure) - the systems that support development
+[Linear Guidelines](linear-guidelines) - how we use Linear to manage development work
 [Release Management](release-management) - how we package software and make it available to customers

docs/engineering/development/linear-guidelines.md

@@ -0,0 +1,57 @@
+---
+title: Linear Guidelines
+outline: [2, 3]
+---
+
+# Linear Guidelines
+
+We use Linear to plan and track our content creation, software development, and customer support work. These guidelines are meant to help us reach a shared understanding of our plans. A little structure and a few standards will go a long way. No need to be overly prescriptive.
+
+## Priority
+
+Each issue should be assigned a priority as it is created. The priority can be adjusted at any time our understanding or the situation changes. Weekly planning is a good chance to review and update priorities.
+
+The following definitions will help us keep the most important activities at the forefront, while not forgetting about issues that may be important later (or never).
+
+- **Urgent:** Requires immediate attention and resolution ASAP.
+  - Examples:
+    1. A customer notifies us of a problem, and we have a support SLA for timely initial response.
+    2. The Koor website is down.
+- **High:** Should be worked on now or next. Aligns with our business priorities and goals.
+  - Examples:
+    1. Issues to reach the next project milestone.
+    2. A new Sales initiative to attract customers in a specific market segment.
+- **Medium:** Should be worked on as we have a chance, i.e., when there are no unassigned Urgent or High priority issues.
+  - Examples:
+    1. A good idea that is not required to reach the next project milestone.
+    2. Polishing or bullet-proofing a feature that is not market-tested yet (i.e., before we know if anyone wants it).
+- **Low:** Keep in mind for later, but do not work on these. Perhaps use these to come up with better ideas.
+  - Examples:
+    1. Ideas from brainstorming.
+    2. Anything that might be suitable when Koor is a lot bigger.
+
+### Priority Rules of Thumb
+
+The general rule of thumb is to only work on High priority issues, except with something Urgent pops up. Also, it might better to work on something of Medium priority than doing nothing. Or you might think of High priority issues that are missing.
+
+An issue that is part of an active project can start as High or Medium, depending on how well it aligns with the next milestone.
+
+When you are not sure how important an issue is, the default priority should be Medium. We can talk about new issues and adjust the level as needed.
+
+If you just want to record an idea for later, mark it as Low priority.
+
+If all we have left are low priority items, we need to dream about bigger and better things.
+
+## Estimates (a.k.a. sizes)
+
+Estimates are about the amount of effort we believe it will take to complete an issue. This is not about elapse time or duration. If you could focus all of your attention without interruption (aside from rest breaks), how long would it take?
+
+- **XS** - takes more time to handle overhead than complete the task itself
+- **S** - can be completed in less than a day
+- **M** - will take 1 or 2 days of effort
+- **L** - will take up to a week (5 working days of effort)
+- **XL** - will take more than a week of effort; should be broken into smaller sub-issues
+
+Do not spend too much time worrying about estimates. Think about the scope and what will need to be done, then pick your best guess.
+
+However, if an estimate ends up being smaller than the effort it is taking, we might say the issue is "blowing up." When that happens, let's use that feedback to adjust our plans. One option is to reduce scope by redefining the issue to be more specific. Another is to add more issues to handle must-do scope that you discovered. In any case, discuss any surprises with the team as you find them.

docs/engineering/development/show-and-tell.md

@@ -1,9 +1,9 @@
 ---
-title: Show and Tell
+title: Progress Reviews
 outline: [2, 3]
 ---
 
-# Show and Tell
+# Progress Reviews
 
 ## Purpose
 

package.json

@@ -1,7 +1,7 @@
 {
   "devDependencies": {
     "mermaid": "^10.7.0",
-    "vitepress": "^1.0.0-rc.40",
+    "vitepress": "^1.0.0-rc.41",
     "vitepress-plugin-mermaid": "^2.0.16"
   },
   "scripts": {