Things to think

  • Engineering productivity can be measured is a bold statement, after so many years of trying to quantify software development. In this article, the author states that most metrics you try to get from a team, can - and will be challenged by engineers. The most simple example is to measure lines of code. Engineeres will find ways to improve the number of lines of code tremendously, without affecting effectivity. On the other hand, not measuring at all won't help either. The bottom line of the article is to measure blockers:

Engineering should instead be about effectiveness: "How able is this engineer to effect positive impact?"

  • Quality of developer tools
  • Frequency and quality of internal activities (like meetings or code reviews)
  • Focused maker time (free from disruptive meetings)
  • Easy access to documentation
  • Psychological safety on the team
  • Work-life balance
  • Presence of other high-performers
  • A fair system of rewards

Screenshot from a talk Gunter Dueck gave about Intrapreneuring

Intrapreneur's Commandments

Documentation done right

There are four categories of documentation:

  • Tutorials (learning oriented)
  • How-to guides (problem oriented)
  • Reference (information oriented)
  • Discussions (understanding oriented)

These categories need structurally be kept apart.

Tutorials

Tutorials are supposed to be the hardest part of a documentation to create. Let a beginner do an exercise to learn using the software. The point is practical knowledge, not theoretical knowledge. Tutorials need to be concrete and not abstract. There should be no explanation. There should be no options or choices of the path. The tutorial writer is in charge of that path. The tutorial must be reproducable under all circumstances.

How-to guides

Recipes to solve a problem to achieve an outcome. In contrast to a tutorial, the learner would not even be able to formulate a problem to solve. How-to guides do not need to start at the beginning. They can assume basic knowledge of the domain. Again, no explanations. They get in the way of actions. Choose practicability over completeness.

Reference

References are purely descriptive. They are supposed to describe the machinery. A reference should not explain what can be assumed as general knowledge of the topic. The reference’s structure should resemble the code base. The wording should be consistent.

Discussions / Background material / Explanation

Clarify and illuminate a topic. Give context and discuss alternatives. Outline conflicting opinions. Make connections. It should not contain guides or technical reference.

Reference