Feature/gen-204 (#35)

* docs: update dev practices, add show and tell

* docs: add more details about dev

docs/.vitepress/config.ts

@@ -7,17 +7,13 @@ export default withMermaid(
     title: 'Handbook',
     titleTemplate: ':title | Koor Technologies, Inc.',
     description: 'How we run our business',
-
     lastUpdated: true,
-
     head: [
       ['link', { rel: 'icon', type: 'image/x-icon', href: '/favicon.png' }],
     ],
-
     themeConfig: {
       // https://vitepress.dev/reference/default-theme-config
       logo: 'koor-logo.png',
-
       nav: [
         { text: 'Home', link: '/' },
         { text: 'Company', link: '/company/' },
@@ -26,7 +22,6 @@ export default withMermaid(
         { text: 'Marketing', link: '/marketing/' },
         { text: 'Support', link: '/customers/support/' },
       ],
-
       sidebar: [
         {
           text: 'Company',
@@ -79,7 +74,11 @@ export default withMermaid(
             {
               text: 'Development',
               items: [
-                { text: 'Practices', link: '/engineering/development/' },
+                { text: 'Overview', link: '/engineering/development/' },
+                {
+                  text: 'Show and Tell',
+                  link: '/engineering/development/show-and-tell',
+                },
                 {
                   text: 'Release Management',
                   items: [

docs/.vitepress/theme/custom.css

@@ -1,6 +1,21 @@
 :root {
-    --vp-c-brand: #19dda5;
-    --vp-c-brand-light: #c3d5c4;
-    --vp-home-hero-name-color: transparent;
-    --vp-home-hero-name-background: -webkit-linear-gradient(300deg, #19dda5, #23a076)
+  --vp-c-brand: #19dda5;
+  --vp-c-brand-light: #c3d5c4;
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    300deg,
+    #19dda5,
+    #23a076
+  );
+}
+
+h1 {
+  color: #9e809a;
+  text-align: center;
+}
+h2 {
+  color: #19dda5;
+}
+h3 {
+  color: #23a076;
 }

docs/engineering/development/index.md

@@ -3,38 +3,85 @@ title: Koor Software Development
 outline: [2, 3]
 ---
 
-# Development Practices
+# Software Development
 
-## Dev Process
+## Development Cycles
+
+Development happens in cycles. A few key cycles drive our work.
+
+1. Weekly dev cycles
+   - We do planning every week.
+   - We account for what has been finished and make sure everyone is clear about what to do next.
+2. Sprint cycles
+   - We group work into 2-week cycles, commonly known as sprints.
+   - Since we are neither following a strict agile process nor releasing every two weeks, the value of this cycle is low.
+3. Release cycle
+   - We should be releasing one or more product areas on a regular basis, at least monthly.
+   - Releases should be frequent enough to show that we are active.
+   - Releases should include enough improvements to be worth the trouble.
+4. Quarterly business cycle
+   - Every three months, we establish goals and plan high-level activities.
+
+Projects cut across cycles. Larger projects can have milestones that target specific outcomes on a shorter timeline.
+
+
+## Dev Activities
+
+Our weekly dev cycle includes the following activities.
+
+1. **Unstructured time** 
+   - vast majority of the week
+   - for coding and creating related artifacts: requirements, designs, usage guides, demos, etc.
+2. **Planning** 
+   - Review projects in Linear.
+   - Update issue statuses, and make sure everyone has assignments for the next week.
+   - Avoid having too much or too little work in progress.
+3. **[Show and tell](show-and-tell)** 
+   - to show the results for the past week
+   - Follow the link and review the protocol for sharing your work with the team.
+   - Help your colleagues by reviewing their work, asking questions, and suggesting improvement ideas.
+4. **Retrospective** 
+   - Once a month or as needed (when people want to unpack a particular incident). 
+   - Reflect on recent past. Acknowledge what is working, and call out what could be better.
+5. **Release demos**
+   - For recording demonstrations of features to share with the world.
+   - Happens as features become ready for use. Ideally we are generating enough exciting results to do this weekly.
+   - At a minimum, we should have videos about major features linked from the release notes of each release.
+
+### Weekly Schedule
+
+**Watercooler**: daily x 3
+**Show and Tell**: Wednesday @ 9 AM Pacific, 50 minutes
+**Planning**: Thursday @ 9 AM Pacific, 25 minutes
+**Retrospective**: async, after Show and tell, due by Planning
+
+## Development Tools
 
 We use [Linear](https://linear.app/) to manage and record our work.
+Our repositories are kept at [GitHub](https://github.com/koor-tech).
+<Badge type="warning" text="ToDo" /> Let's build a complete list at some point.
+
 
-### General flow
+## Development Stages
 
-1. Create projects to organize changes
-2. Maintain backlogs to manage the activities of completing projects
-3. Work in 2-week cycles. For each cycle:
-   1. Choose items from the backlog to work on
-   2. Assign an owner to each item. The owner is responsible for completing the item. Collaboration is encouraged.
-   3. Completed changes must be reviewed by peers. All feedback should be addressed by taking the suggested action or explaining why not.
+### Feature requirements and functional design
 
-### Feature Development
+Show in words and pictures what features show do. Provide a rough idea of how they should work. Everything in the early stage is a sketch, to be filled in more completely as the feature is developed. Look at the big picture and figure out how the feature works are part of the whole product.
 
-A feature is something the software does or allows a user to do. Features are developed in stages by starting with the most basic thing that makes sense to enable. Additional work is done to expand the feature, one capability at a time. We can iterate until the feature is working as desired in every way.
+Consider the use cases that a feature is meant to satisfy. What is a user trying to do? How does the feature enable the user to do that?
 
-One way to work iteratively is by using user stories. A story takes the form of:
+User stories help to define all of the angles of a use case. A story takes the form of:
 
 > A \<class-of-user\> wants to \<action-to-take\> so that \<desired-effect-of-action\>.
 
-#### Definition and design
+For example: 
+
+> A *salesperson* wants to *keep a list of prospective customers* so that *he or she can send promotional coupons*.
 
-1. Each feature should be explained well enough for someone to get started.
-2. Do enough feature design to understand what is to be done.
-3. Do technical design to address how the feature's requirements will be satisfied.
-4. Break the feature work into stories, written from the perspective of an intended user.
-5. Add stories to the backlog.
+Under that heading, describe all of the functional details the system should handle to make this happen. A functional detail defines what should happen, not how. Leave the question of how to those implementing the features.
 
-#### Working on stories
+
+### Working on stories
 
 1. When a story is picked up for development, that is the time to ask all of the detailed questions.
    1. Review exisiting designs. Create new designs to fill design gaps.
@@ -45,3 +92,26 @@ One way to work iteratively is by using user stories. A story takes the form of:
    4. Add a system test to cover the happy path where everything is working.
 2. Do a PR on your story. Make adjustments based on review comments.
 3. Stage completed work as you go. We should be able to use all of the completed stories at the end of each cycle.
+
+
+### Implementation
+
+<Badge type="warning" text="ToDo" /> Make this more complete
+
+Briefly, we use the requirements and stories to get features working. At the same time, we add tests that prove things are working as prescribed. For the moment, we are leaving this to developers, leaning heavily on PR reviews and show-and-tell to catch problems.
+
+### Testing
+
+Everyone knows that tests should be written along with implementation. Also, there is always room to add more automated testing once a feature is complete. We need to be disciplined about rounding out our test coverage for what we just completed before moving on to the next features.
+
+We also have the option of running features in our demo system as a way to ensure that they are working as expected. Recording videos of the demo system is a great way to show customers what to expect.
+
+### Release, distribute and deploy
+
+When we build a release (see [Release Management](release-management)), we need to make sure it is distributed where customers can find it. Since we do not run customer systems, deployment is up to our customers. We should deploy to our demo system to make sure the instructions for deployment still work and are easy to follow.
+
+## Related topics
+
+[Show and Tell](show-and-tell) - sharing details of our work as we go
+[Infrastructure](infrastructure) - the systems that support development
+[Release Management](release-management) - how we package software and make it available to customers

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

@@ -0,0 +1,62 @@
+---
+title: Show and Tell
+outline: [2, 3]
+---
+
+# Show and Tell
+
+## Purpose
+
+We are a fully remote company, and software development is primarily a mental exercise. These factors lead us toward working alone. Proactively sharing what we have been working on is one way to bring us together. Through a ritual called "Show and Tell," we explain to each other recent accomplished and our creative work in progress. This activity is useful for a few reasons.
+
+1. It forces us to organize our thoughts and explain our logic and reasons to someone else. Sometime this has a side effect of helping us realize where our designs or choices have gaps.
+2. It helps others understand newer parts of the system and the choices that were made while building them.
+3. It is an opportunity for everyone to learn and to share ideas, making us a stronger team.
+4. It is a forcing function to complete the bit of work.
+5. In the case where you are stuck, you will need to explain what you have done and what the problems are to get advice about what to try next.
+
+Show and tell is primarily for an internal audience of co-workers. Sometimes we end up with a recording worth sharing on YouTube. That is secondary to the purpose of staying in touch with what each of us is doing.
+
+## Guidelines
+
+Demonstrating your work is a skill that takes practice to hone. Take the time to do this every week, and you will improve quickly.
+
+While you are learning, follow a simple format:
+
+1. **Short overview**: Say what you are going to present in 1 or 2 sentences.
+2. **Show the goal**: If the code is working, start by showing the functionality in action. If it is not working yet, explain what you are trying to get it to do.
+3. **Explain the architecture or design**:
+   1. What are the parts?
+   2. Are components organized into layers?
+   3. How are they meant to work together?
+4. **Show code / how it works**:
+   1. Choose two or three interesting samples of code
+   2. Make sure your font is big enough for people to see.
+5. **Take questions**: Think about pausing every 5 minutes or between topics to see if there are questions.
+
+Highlight or deep-dive at least one major effort of the past week. You can also show a few different things if they are smaller and quick to explain.
+
+Take the time to review other people's summaries. Participate to the best of your ability, even if that is mostly to watch / read, ask questions, and learn. Contribute feedback and questions if you are able.
+
+Present during the show-and-tell meeting or share asynchronously in writing or by recording a video. You can even share before the meeting and use the meeting time to answer questions and hear feedback.
+
+<Badge type="warning" text="ToDo" /> Let's figure out a good way to share asynchronous show-and-tell updates. Need a way to exchange comments, keep an archive.
+
+### What to show
+
+Choose something that would be of interest to others. It could be:
+
+* a design
+* a bug - before and after the fix
+* an entire new feature
+* an improvement to a feature (e.g., better UX) or the code (e.g., refactoring)
+* a set of automated tests
+
+Limit the scope by focusing on what was done recently. Choose an area that:
+
+* you want to show off, 
+* made you learn something, 
+* you are having problems with, 
+* you have questions about, 
+* others should know about, 
+* might benefit from other opinions.

package.json

@@ -1,7 +1,7 @@
 {
   "devDependencies": {
     "mermaid": "^10.3.0",
-    "vitepress": "^1.0.0-rc.2",
+    "vitepress": "^1.0.0-rc.4",
     "vitepress-plugin-mermaid": "^2.0.13"
   },
   "scripts": {