cborenstein

I think good tech talks (especially ones that are highly technical), are ones that make the high-level context for why we should care about the technology we're learning very clear.

I'd recommend checking out https://femgineer.com/present-book/ and the corresponding youtube channel: https://www.youtube.com/user/Femgineers

Her lessons on using storytelling in your talk to explain and reinforce the high-level value might be helpful for you as you structure your talk.

Thanks for sharing your guidelines.

> Review and edit messages before sending

Part of the joy of Slack is that sending messages to your team is super low-friction so more people are likely to contribute. The example use case is "I have this thought-through proposal I'd like to do. Is it okay with you." In this case it makes sense to review more thoroughly before sending in order to communicate the proposal more clearly.

In other cases, you may want to engage in more back and forth as you debug something together or make a plan together. In these debugging/planning sessions, I think it’s valuable to have the full thought process of the team recorded in Slack. This unfiltered discussion might provide useful context to someone else later.

I like to augment this frictionless back and forth with a summary at the end of the discussion. This makes it easier for someone other than those involved in the conversation to benefit from it. And then they can refer to the full conversation for more details.

I'm one of the creators of a tool that's designed to make these summaries accessible (https://bytebase.io).

Awesome article, thanks for sharing.

You make a great point that comments aren't trustworthy but can still provide a useful breadcrumb.

My thoughts are that an overall documentation strategy can include several lines of defense based on how narrow or broad the context you need is.

1. write "self-documenting" code using good variable names, encapsulation, etc.

2. write comments to explain anything non-obvious in a specific line or block of code

3. use git commit messages or git pull request descriptions to explain why a feature was built a certain way

4. use an external documentation source (I'm one of the creators of one called https://bytebase.io) to capture higher-level context like why we're working on this feature.

Recently wrote a blog post describing a strategy for 3 and 4: https://medium.com/better-programming/daily-habits-to-turn-y...

In my experience, code documentation is painful because people often try to maintain perfectly comprehensive formal docs and the expectation is too high. Aiming for perfection instead of iterative improvements can feel intimidating and painful.

I recently wrote this blog post on how you can use lightweight daily habits in git and https://bytebase.io (I'm one of the creators) to avoid the dreaded "Docs Overhaul" that seems to happen every couple of months.

Blog Post: https://medium.com/better-programming/daily-habits-to-turn-y...

The main idea is to capture small chunks of context as part of your regular coding routine. This can be in a git commit message if it closely relates to code or in an external knowledge sharing tool if it is higher level context.

I’d recommend two phases when writing notes:

1) dump everything into your notes that might be useful

2) organize and highlight the most important stuff

---

I’m one of the creators of https://bytebase.io and that’s where I take notes. We’ve designed Bytebase to decouple the capture and organize phases.

- In my first pass when taking notes, I write down anything that might be helpful later.

- Each note is captured as a “byte” - a short chunk of information.

- I then go back and re-organize by adding tags to categorize certain bytes and using drag and drop to move things around.

Another resource that might be useful is video recordings from the DjangoCon conferences. Here's the youtube channel for DjangoCon US: https://www.youtube.com/channel/UC0yY6a79pPY9J0ShIHRf6yw

In my experience, remote engineers are often some of the most productive engineers at an organization.

When any engineer can demonstrate a strong track record of shipping, any idea of "laziness" goes away pretty quickly.

I think one of the reasons why "laziness" comes up is because remote engineers aren't physically in the office to be shoulder tapped for questions (though so many questions now go in Slack anyway).

A somewhat opposite problem I've seen is that when people work remote, they kind of "forget to stop" and end up working way more than a standard workweek.

A start to solving both of these issues when working remote is to establish a clear schedule of your working hours and your "availability for questions" hours. I.e., make it clear 1) when you're working and when you're not 2) when you're available for answering questions vs reserving your time for working in flow.

Can use something like a Slack status to remind colleagues.

Break things down.

I'd start by getting an overview of the problem - in this case it's probably chapter names in a book.

Then for each module, break down what you'd like to learn further into sections that take < 2 hours to complete thoroughly.

After each 2 hour module, write down your key takeaways of the trickiest part you learn and pause.

Then, when you're ready, resume for the next intense chunk.

You can re-read your highlights at the end of the day to help absorb more deeply.

I've also found the Cornell Notetaking method (http://lsc.cornell.edu/study-skills/cornell-note-taking-syst...) to be a helpful guide.

It includes the "summarizing" step and a recommended structure for organizing notes both as you're reading/watching and when you're solidifying this knowledge.

Thanks for your question! We don't support integrations other than Slack yet but plan to add more soon as well as an API.

Mind shooting me an email so I can learn more about what your team needs?

Disclosure: I am a founder at bytebase.io, currently in closed beta. We're building Bytebase with this kind of use case in mind.

Wikis - we found wikis are too heavyweight and formal to be used consistently for recording learnings.

Slack - in our experience, Slack makes capturing learnings easy but organizing and keeping track of learnings difficult.

Our goal with BB is to make recording a learning as convenient as writing a Slack message AND to make organizing and keeping track of these learnings similarly easy.

You can write bytes directly in Bytebase or save them from Slack.

Would love any feedback or ideas. Email me (cara@bytebase.io) to get access to the closed beta with HN in the subject line.

Disclosure: I am a founder at bytebase.io, currently in closed beta.

My former team used Confluence and Google Docs for knowledge sharing and found that it worked great for planning projects, but fell short for things that change quickly or are relevant for only a short period of time - code commands, debugging tips, meeting takeaways.

We relied on slack and personal notes for these tidbits which resulted in the information being difficult to find.

This experience inspired us to start Bytebase, the byte-size knowledge base for engineering teams.

Everything in Bytebase is a "byte" - a short chunk of information - not a document, and bytes can be composed of other bytes.

Bytebase makes it easy to capture and share bytes using a shortcut-heavy UX that feels familiar to engineers.

Would love any feedback or ideas. Email me (cara@bytebase.io) to get access to the closed beta with HN in the subject line.

Might be fun to integrate with an API like twitter or twilio so you can practice using an HTTP client (I use axios) with react.

Design Your Life https://designingyour.life/the-book/

applies engineering design principles to your career and personal goals

very interesting - that seems like a good and still pretty simple rule too. I feel like if the docs are organized well then volume shouldn't matter but at the same time having fewer docs means less room for error in organizing.

that's a good idea. would you recommend a file/directory structure or just tags/keywords next to each command in a flat file? I'm wondering if the directory structure will feel too clunky and result in less getting written down.

very interesting. It seems like a good idea to not worry about the structure when first writing things down but to reserve time at the end of the week to organize. where do you usually write your "temp" notes? do you use any structure or not until the end of the week?

thanks for sharing - that makes sense. Where do you usually write your runbooks? In a google docs/confluence type wiki or with your code? How do you organize them so that you can find/share them quickly?

thanks for all of your suggestions. What do you find is the best way to organize the command-line incantations (what a great way to describe them) and click sequences? do you write them in something like google docs or confluence or in your code?

I like that simple rule but I think it will lead us to have a lot of small notes super quickly, which might be difficult to weed through later. Do you find yourself with this problem?

How do you make the small commands findable/understandable while minimizing time spent on docs? When do you refactor and what does that look like?