Levels of Developer Documentation

A friend has been struggling with under-documented projects (*cough* zoo software). This raised the question, what makes good documentation? And what is a good documentation system? Here’s my opinion backed with some sources.

March 18, 2022 · 2 min

Development Cycles Checklist

A junior developer recently asked for a daily responsibilities checklist. This question made no sense to me at first. A developer’s job isn’t so routine as a daily checklist. However, it sparked me to think about how a developer’s regular activities can be described concisely.

January 21, 2022 · 6 min

Foundation of Software Measurement

Software Engineers are differentiated from other programming disciplines by economical, repeatable, and reliable results. Such consistency requires measurement, data on which to make informed decisions. I propose that source control and work item tracking are the kernel of such process.

December 31, 2021 · 2 min

Notes as Data

I’ve fallen in love with Markdown and it is slowly permeating all of my documents. The latest addition is notes, which Markdown makes easy to reference either manually or programmatically!

March 5, 2021 · 6 min

Technical Collaboration

“The need for reviewing was so obvious to the best programmer that they rarely mentioned it in print, while the worst programmers believed they were so good that their work did not need reviewing” – Daniel Freedman and Gerald Weinberg IBM found that every hour of code inspection saved 100 hours of related work (Code Complete, p.480). Pair programmers produce higher quality, more maintainable, code in only 15% more time than an individual (Pair Programming Benefits), and inspected systems require 1/10th the maintenance of non-inspected systems (Code Complete, p. 485).

December 15, 2018 · 4 min

Spec Docs

“Program specification is the process of taking a requirement and reducing it down to the point where a programmer’s skill can take over. It is an act of communication, explaining and clarifying the world in such a way as to remove major ambiguities” –The Pragmatic Programmer

December 8, 2018 · 6 min

Agile

“Individuals and interactions over processes and tools Working software over comprehensive documentation Customer collaboration over contract negotiation Responding to change over following a plan” – Agile manifesto Agile (in its many flavors) is the de facto standard for work management in software. It identifies core priorities for software collaboration and outlines a flexible structure for managing requirements. This facilitates best practices and a shared methodology.

December 2, 2018 · 6 min

Requirements

The most important single aspect of software development is to be clear about what you are trying to build. - Bjarne Stroustrup (inventor of c++) Plans are worthless, but planning is everything. - Dwight D. Eisenhower

November 25, 2018 · 5 min

Iteration

“…the incompletenesses and inconsistencies of our ideas become clear only during implementation.” – Fred Brooks (Mythical Man-Month) “It is widely accepted that creative design is not a matter of first fixing the problem and then searching for a satisfactory solution concept; instead it seems more to be a matter of developing and refining together both the formulation of the problem and ideas for its solution, with constant iteration of analysis, synthesis, and evaluation process between the two “spaces” – problem and solution.” - Nigel Cross and Kees Dorst

November 15, 2018 · 4 min