docs: revise communications

docs/company/communication.md

@@ -1,77 +1,111 @@
 ---
 title: Communication
+outline: [2, 3]
 ---
 
 # Communication
 
 ## General guidelines
 
-We are a fully remote company. That means we make heavy use of collaboration tools: Slack, Google Meet, Zoom, Linear (for project management), Status Hero for daily individual progress updates, and email, etc.
+We are a fully remote company. That means we make heavy use of collaboration tools: Slack, Google Meet, Zoom, Linear, and email, etc.
 
-Since we each work at hours that make sense for our location on the globe, we need to make an extra effort to communicate. This can work to our advantage, since the extra care in communicating means we will write down more information. We have longer cycles to think and confirm our understanding of any given topic.
+Since we each work at hours that make sense for our location on the globe, a lot of our work will be done asynchronously. That means we need to make an extra effort to communicate and coordinate. This can work to our advantage, since the extra care in communicating means we will write down more information. We have longer cycles to think and confirm our understanding of any given topic.
 
-What we miss are the visual cues. Is the other person paying attention? Are they confused by something we said? Are they in agreement, or do they want to make a counterpoint?
+What we miss are visual cues. Is the other person paying attention or distracted? Is something we said confusing or off-putting to others? Are they in agreement, or do they want to make a counterpoint?
 
 What is the same is that people always misunderstand each other. We all bring different perspectives and experience that leads to how we perceive what is said.
 
-We will not solve all communication problems with some points in a handbook. However, we can try to operate in a way that makes good communication more likely. The number one guideline over all others is:
+It is the responsibility of all parties to seek clarity. Ask questions. Repeat back what you have heard to confirm understanding. Rephrase your points as needed to reach understanding, even if you disagree with each other.
+
+We will not solve all communication problems with a few points in a handbook. However, we can try to operate in a way that makes good communication more likely. The number one guideline over all others is:
 
 ::: tip
 Assume good intentions.
 :::
 
 This opens the way for patience and courtesy. If there is contention, you can first seek understanding. Once you see the disconnect, you can discuss reasons and alternatives.
 
-The quickest way to closed communications is to assume the other person is an idiot.
-
-## Levels of confidentiality
+### Confidentiality levels
 
 Consider the audience for your message.
 
 - Public
   - Any message meant for the outside world. Public communication includes anything on our website, in email signatures, in recordings that are shared openly. If anyone might be able to see it, it is public.
+  - This handbook is shared publicly. We are happy to divulge how we operate as a model for others to follow, and we are open to feedback about potential improvements.
 - Internal
-  - A lot of our communication will fall into this category. Consider project work, planning, company status, general customer activities and other such topics. We may choose to make such communication public (such as this handboook, or an internal progress demo), but not by default.
+  - A lot of our communication will fall into this category. Consider project work, planning, company status, general customer activities and other such topics.
+  - Sensitive information, such as bank account numbers, the names of our customers, and more, is considered to be internal.
 - Customer
   - Interactions with customers need to be treated with confidentiality and privacy in mind.
+  - Be aware that some of our Slack channels are shared with customers.
 - Employee
   - When discussing matters related to employment that are private in nature.
 - Priviledged
   - Information that may only be shared with specific individuals for legal or competitive reasons.
 
-## Internal communication
+### Internal communication
 
 - Favor Slack over email for internal communications.
+  - Use emojis and words to acknowledge messages
+- Anything non-transient (that needs to live beyond a few weeks) should be captured in a Google doc or one of our productivity tools.
 
 ## Meetings
 
-Although related to communication, this might need its own page. Someday...
+Meetings are useful for real-time collaboration. Otherwise, we should defer to asynchronous means of communications. We have a few meetings that are standard parts of our work week.
+
+If you were ever in a meeting that was a waste of time, it's good to raise that point. Perhaps you do not need to attend, or the meeting needs to be organized more effectively.
+
+### Progress reviews
+
+60 minutes; weekly
+
+Weekly progress reviews are a way to share our progress with each other. Choose one or two highlights, and talk about what you were able to accomplish during the previous 7 days. Each employee should share each time. It could be a work in progress or something you are struggling with.
 
-### Progress Reviews
+Each person gets about 10 minutes to share. Presentations may be shorter than that, but not too much longer. (For topics that generate significant interest, consider scheduling a separate deep dive meeting to take more time getting into specifics.)
 
-1 hour; weekly
+With 6 people, we should plan for progress reviews to last about an hour.
 
-Everyone shares an important project they are working on, showing progress in the past week or since last discussed.
+Come to the meeting prepared with what you will share. That way, you can can devote your attention to others. If you don't prepare, you will be distracted worrying about what you will say. Also, you will make everyone else wait while you find that bit of code or get something to start.
+
+If you cannot attend the progress review, consider recording a short video of your progress report. Use Meet or Zooom and share the recording in the meeting notes (attached to the meeting invitation).
 
 ### Planning
 
-30 minutes; weekly
+25 minutes; weekly
+
+Planning is when we decide on the work to pick up for the coming week. This activity helps us keep our backlog updated and aligns us as a team on what is most important at the time.
+
+Each project owner leads a review of items in Linear, adding any that we realize are missing, and assigning the work to individuals. When everyone is assigned the most important work for each active project, the meeting is over.
 
-We review each project, update statuses of items to match the current state, and settle assignments for the new cycle. Longer planning discussions and project collaboration happen outside of this meeting.
+This is a time to watch for work that never seems to finish, as well as anyone who has too much work in progress. Everyone should have one or two primary focal areas, not more.
 
-### Water Cooler
+To make this meeting efficient, project owners can do long-range planning and backlog grooming before the meeting.
+
+As the week progresses, everyone should pay attention to the items they are assigned to in Linear and make sure the statuses reflect reality (in progress, in review, done). This discipline keeps the boards up to date, which speeds up the planning session. It's also a great way to show that you are paying attention to your assignments.
+
+### Water cooler
 
 15 minutes, 3 times per day M - Th, once on Fridays
 
-For casual discussions, a few chances each day to get to know colleagues better.
+For casual discussions, a few chances each day to get to know colleagues better. Social topics should get priority at this time. However, it's okay to talk about work items, especially if that's what people want to discuss.
 
 ### Retrospectives
 
 1 hour; monthly
 
-Everyone has a chance to share what is working, what is not working, and ideas to try.
+Everyone has a chance to share what is working, what is not working, and ideas to try. The subset of ideas that we agree to try should be tracked in Linear. It's a good idea to follow up in subsequent retrospectives to see if what we tried had any impact.
+
+### One-on-ones
 
-## Using Slack, StatusHero, email, video conferencing (Zoom / Meet / Jitsi)
+These are meetings between a manager and his or her direct report. They should be scheduled weekly with a running agenda. The best practice is for the employee (a.k.a. direct report) to write down the answers to these questions:
+
+- What did you accomplish during the past week?
+- What are you working on next?
+- What other questions or topics would you like to discuss?
+
+Try to do this a few hours before the 1-1 so that the manager has time to review. Sometime, this will be sufficient, and the meeting can be canceled for the week.
+
+## Communication tools
 
 ### Slack
 
@@ -89,37 +123,30 @@ The medium is designed for multi-way communication, and being remote means we ar
 
 Slack is not the place for long-lived documentation. Communication that is more permanent belongs in this handbook, a Google doc, a README file in a code repo, a PR, or another place for artifacts.
 
-### Status Hero
-
-We use StatusHero to keep a daily record of what everyone is doing. The tool encourages a good habit of reflecting daily about your priorities. If you accomplished something, you can give yourself a gold star. If you got distracted or planned to much, use that observation while planning your next steps. By writing down and sharing these thought in StatusHero, we can cheer each other on.
-
-Ten minutes of reflection each day raises our consciousness. Being conscious of our choices allows us to work with purpose. Time will pass regardless, so let's make the most of it.
-
-The tool is only useful when we use it every working day. Here are some guidelines:
-
-- Use Status Hero every day.
-  - A brief summary about "yesterday" and "today" is sufficient.
-  - Be honest with yourself about what you did not finish or forgot about completely.
-- Missing a day or two each week from time to time is forgiveable.
-  - Missing too often leaves a hole in awareness, leading to doubt about what you are doing.
-  - This is one data point. Maybe your activity speaks for itself. There should be plenty of other evidence that you making progress. Why not mention it?
-- Be informative. We are sharing so others can understand each other's context.
-  - Something like "Worked on the project" is too vague. Make it more like "Added screen for picking a color scheme."
-  - Do not write to impress others (i.e., your manager). Treat it more as a journal entry for yourself (that others will see).
-  - Fake news is discouraged.
-
 ### Email
 
-- Email may be the best way to communicate with a group that spans multiple companies.
 - Favor Slack over email for internal communications.
+- Expect longer turn-around for email based communication.
+- Remember that email is more of a permanent record, for better or for worse.
+- Email may be the best way to communicate with a group that spans multiple companies.
+  - For discussion with customers, set up a shared Slack channel to avoid having to use email.
+  - Even for vendors, we favor setting up a Slack channel.
+
+### Video conferencing
 
-### Video Conferencing
+This relates to Meet, Zoom, Jitsi, basically anytime we are sharing video and voice in a group setting.
 
 - Having cameras on is best.
-- Without physical cues, it can be hard to know when to stop talking. Interruptions are expected. You can use your polite words, then make your points.
+  - Obviously, there are times when you want them off.
+  - Video over slow networks can be a problem.
+  - Otherwise, favor being seen.
+- Interruptions are normal and expected. Without physical cues, it can be hard to know when to stop talking.
+  - If you are not speaking and have a point or question about what was just said, it's okay to try cutting in.
+  - If you are speaking and someone is cutting in, pause and see if their point should be addressed immediately.
 - Be part of the discussion. Express your views and ideas without waiting for a better time, which may never come.
   - Volunteer to be a note taker. Help push the agenda along.
-- When sharing your screen, if you are sharing code, make sure the font is big enough for others to see.
+- When sharing your screen to show code, make sure the font is big enough for others to see.
   - Otherwise, you are not really sharing. You might as well wave your hands around.
 - Give the meeting your attention.
-  - No coding, no closing little tasks, no reading articles.
+  - No coding, no closing little tasks, no reading articles or browsing.
+  - Disruptions happen while working from home. That's okay. This point is more about "multi-tasking" during a meeting.

docs/company/employees/index.md

@@ -7,7 +7,7 @@
             title: 'Founding Engineer',
             links: [
                 { icon: 'github', link: 'https://github.com/galexrt' },
-                { icon: 'twitter', link: 'https://x.com/galexrt' },
+                { icon: 'x', link: 'https://x.com/galexrt' },
             ],
         },
         {
@@ -24,7 +24,7 @@
             title: 'Cloud Storage Engineer',
             links: [
                 { icon: 'github', link: 'https://github.com/Javlopez' },
-                { icon: 'twitter', link: 'https://x.com/devjlopez' },
+                { icon: 'x', link: 'https://x.com/devjlopez' },
             ],
         },
         {
@@ -33,7 +33,7 @@
             title: 'Founder, CTO',
             links: [
                 { icon: 'github', link: 'https://github.com/dave-at-koor' },
-                { icon: 'twitter', link: 'https://x.com/DaveOfSanRamon' },
+                { icon: 'x', link: 'https://x.com/DaveOfSanRamon' },
             ],
         },
         {
@@ -42,7 +42,7 @@
             title: 'Cloud Storage Engineer',
             links: [
                 { icon: 'github', link: '' },
-                { icon: 'twitter', link: 'https://x.com/' },
+                { icon: 'x', link: 'https://x.com/' },
             ],
         },
         {
@@ -51,7 +51,7 @@
             title: 'Cloud Storage Engineer',
             links: [
                 { icon: 'github', link: '' },
-                { icon: 'twitter', link: 'https://x.com/' },
+                { icon: 'x', link: 'https://x.com/' },
             ],
         },
     ]