Every report should have a "constraints" chapter

Okay, slightly clickbaity title - not every report, and it doesn’t have to be a whole chapter. Moving on…

I think that a chapter titled “constraints”, “personal factors”, “context” or something to that effect should be normalized in report writing. The idea is that, in contrast to the other chapters, there would be a dedicated place to capture all the non-scientific reasons why certain decisions are made

You might mention that,

• motor A was used as it was the only part available/within budget/left over from a previous project, even though motor B was objectively a better fit
• the authors lacked knowledge in this area, so we went for the easiest option
• the decision was made arbitrarily, as we couldn’t find a methodology to decide “properly”
• we tried option A (which didn’t work), but could modify the implementation to use option B (which was similar) even though option C was a better choice (albeit so different from option A that it would have necessitated starting again)
• we wrote the program in Python because it’s the dominant language in our organization, and the authors are most familiar with it
• we wrote the program in Rust because everyone’s doing it nowadays, and we wanted to test how well the language works for our needs
• the authors knew the STM32 very well, so other micro controllers weren’t considered

So, why should this chapter be included?

While a report should describe the scientific method by which decisions were made, there are always real world constraints which at times outweigh all other factors. I find that the current norm is to simply pretend that these constraints don’t exist when writing the report, even when they play a large role in the project, which makes reading and recreating quite confusing

A key point is that people have differing levels of knowledge (and imposter syndrome is a thing), so if someone makes a decision which you disagree with, but you believe them to have more knowledge than you, changing things (perhaps because of your own constraints) can cause huge amounts of uncertainty

Similarly, organisations have differing budgets, person-hours that they can allocate, licensing requirements, and so on

Does it need to be a whole chapter?

Having a chapter dedicated purely to personal constraints which apply to the authors (but not necessarily others) would nudge people to actually spend time documenting these factors (since you can’t leave a chapter or subsection blank) and would help readers understand the context within which decisions were made in an easy to follow way

A dissertation’s chapter list might be,

1. Introduction
2. Literature review
3. Methodology
4. Constraints
5. First contribution
6. Second contribution
7. Third contribution
8. Conclusion

The constraints chapter could be subsection of the methodology, or of each contribution

• 5.1 Component choice

• 5.1.1 Power requirements

• 5.1.2 Speed requirements

• 5.1.3 Personal constraints

  The authors only have experience with type A components, and don’t currently have enough time to learn about type B

What about projects which don’t involve reports?

I think series of informal blog entries could be useful for situations which don’t result in a report of sorts. Something like,

27 November 2020
A. Knemeyer

This week we discovered that an encoder was broken - I'm not
sure how that happened. We ordered a different model as the 
previous one was out of stock with local suppliers. The part
is described as a drop-in replacement on the website

I started implementing a new foot position control strategy
(impedance control). We suspect MPC would be a better fit, 
but it would require a lot of work and and I'm not familiar 
with the field. Our initial tests indicate that impedance 
control will be good enough

Finally, our temporary solution of hot gluing the plate onto
the floor seems to be holding well. It will definitely break 
at some point, but there are more pressing things to work on
at the moment

This gives vital context - the people who eventually take over the project now know,

• why there are two different encoder models being used (it’s not for technical reasons)
• why impedance control was chosen, even though most people in the field would tell you that MPC is a better choice (it was quicker to implement and “good enough”)
• what to investigate if the plate starts giving issues (it’s hard to see that it’s being held by hot glue, without removing the plate)
• who made the decision (perhaps they can give more context, if they’re still within the organisation)
• when the decision was made

It doesn’t have to be anything fancy, like a dedicated website or personal blog - just text files in a history/ folder could be enough. Schedule 30 minutes for a weekly write up on a Friday, and you’re done. I don’t think it’s necessary to tag each write up (pre-empting everything you expect to be useful is quite difficult) especially since regular search (ctrl+F) is pretty fast

And programming projects?

In a pure code project, this context can often be supplied using comments and Git commit messages/git blame. Higher-level architecture decisions (which don’t necessarily belong in any a specific file) might benefit from the history/ folder approach, though

It’s worth pointing out that others have written about keeping a changelog and writing good Git commit messages

Context

Finally, some context for why I wrote this blog post: I took over a robot leg platform, and am confused by some of the decisions. I’m nervous to change parts of the code - was it written this way to account for some corner case? Or did they simply not know the language very well?

I want to replace a seemingly poorly chosen part - is there something I’m not considering? Or was the designer working within constraints which don’t apply to me? When was this decision even made?

Luckily, there are people I can talk to who know most of the context, although that won’t stop me from ranting on my blog :)