Spent some quality time with a garbage disposal this afternoon, going to spend some quality time with a plumber tomorrow…ugh

 

I am trying out Dialog, the Android app for micro.blog, seems to be working well, can monitor the timeline and respond to posts..

Writing documentation is a good thing

Recently, I read a post on the Digital Ocean blog (Documentation As An Open Source Practice) talking about best practices for documenting open source project repos (like Github). The main focus of the post was on providing community-focused documentation (code of conduct, contributors, etc.). I agree that those are good, but it does not tell the whole documentation story. The Write The Docs site has a terrific beginners guide to documentation for a software project. Here are some of my own tips I have passed on to other engineers.

  • Pick a topic
    • What do I need to know to do my job?
    • Is it on the wiki?
    • “Handy tip: write down the things you learn so you don’t have to remember them.” (via @KenSmith)
  • Identify your audience
    • Who are you writing for?
    • What should they know already?
    • What do they need to know?
  • Creating instructions or a checklist for a task
    • Perform the task and take notes as you go
    • Add setup details as needed
    • Add equipment/tool list if applicable
    • Print your initial draft, then repeat the task following your instructions
    • Mark up the draft with additional information if needed to perform the task
    • Add the draft writeup to a wiki or other tool
    • Example – How to Write A HOW-TO document
  • Final Thoughts
    • Writing things down is important
      • If it’s not written down, that information could be lost
    • Updating things is important too
      • Information can be written down, but incorrect or out of date
    • Break the writing down to make it easier to start
      • Use timeboxing (Example: write for no more than 15 minutes at a time)
      • Copy/paste can be your friend
        • Copying text from application windows
        • Screenshots
      • Keep a Word document open and type a running set of bullet items, then do some editing, then paste into a wiki page
    • It’s ok for your first draft to be shitty (link to Anne Lamott piece on writing)
    • Treat yourself after doing some writing!

     

Can we improve the quality of our work?

Recently, I finished reading “The Checklist Manifesto” by Atul Gawande (excerpt in The New Yorker magazine). In the book, he describes how he discovered the power of checklists to ensure that surgery was safer, that buildings could be built on time, and that pilots could recover from emergency situations, among many examples. To me, the takeaway is that many processes are complex, and using checklists to make sure that the process is followed and nothing is left out or missed, which results in a higher quality product or service (fewer errors/defects). I found it to be an inspiring book.

Seth Godin, marketer supreme, also has commented recently on quality. In Quality and Effort, Seth relates a story about creating systems to avoid bad experiences for users. In his first iterations, the result was pretty good, but not perfect. He describes how he changed the system of creating quiz questions/answers to have half the team create the questions and the other half try to come up with better answers and pay a bounty if the new answers were more correct than the original.

The result of the new system? Zero error for the next 5,000 questions.

My last example is Philip Crosby, author of Quality Is Free and Quality Without Tears. His main definition of quality was conformance to requirements – the product or service should meet or conform to whatever requirements are set for that product or service. Another part of his quality system was that processes should be done right the first time, that there should be zero defects in the process and the product/service. Many companies and industries resist this level of quality. but Crosby points out that many companies have zero defects in their payroll operations. To quote from Quality Without Tears, pp. 75-76:

Payroll doesn’t make mistakes.

Is that because they are such dedicated souls? Certainly they are, but the importance of the work does not necessarily raise performance standards. If that were so, one would think that people working in space exploration would never err. However, you can get used to anything, and bad performance standards occur eventually.

The reason that payroll does so well is that people just won’t put up with errors there. They take it very personally when something is wrong with their paycheck.

So, in this example, the expectation/standard is “zero defects” – no errors.

As a software engineer working in the aviation industry, where we have many processes and checklists, I work to create software and artifacts (requirements, tests, etc.) without defects, but most of the time, my fellow workers and I manage to make a few mistakes along the way. Maybe it is time to see if we can construct our systems to prevent such errors. It’s worth a try!

Read Microblogging

The idea of microblogging on my own website is something I’ve been kicking around for years. Instead of posting short pieces of text to Twitter, longer pieces of text to this blog, and photos to Instagram, why not just post all of that stuff here? I could still cross-post to other sites if I wante…

I liked this article for the discussion that the author presents about where, when, and what to post. This is something important to work out for yourself when you start blogging primarily in your own space. As for when to blog, I like the advice from Ron Chester:

The best time to blog is when you have something to say. If you have something to say, the writing will be easy. For me, these things usually come from a personal experience, anything from a simple observation to a full-blown epiphany. Write about it in the moment, if you can.

 

How can I find out who I am following on micro.blog? I have looked through the help, but have not found anything yet…. cc // @manton @macgenie