Where's your GPS
The four types of documentation
You probably already noticed from the title of this letter, the topic of documentation is still important to me. Now that I began spending time with it I notice the many different aspects of documentation. And there’s more than I thought.
Today I want to share a resource with you that taught me about the four different levels/types of docs. I didn’t even know that there were four levels, or why they mattered. They start with something very important:
It doesn’t matter how good your software is, because if the documentation is not good enough, people will not use it.
Stardom (continued)
I received great replies to my letter last week. I want to quote two for you today.
First is Jacob Wyke on the question why these people become some kinds of star for you an me.
I think its because they teach people things, and so generations of developers look up to them as they taught them things.
Stardom
Code Quality through high-quality docs
Hi friend.
I am going to drum the quality drum again. This is a big topic and I know for a fact that I haven’t even scratched the surface of what there is to say about it.
About a month ago I wrote
I’d like to admit, I never had a mentor or teacher who showed me how to properly document software. It was all learning by doing. If you don’t mind, I’ll take some future episodes of this newsletter to document (see what I did there? 👅) my findings and further thoughts about this topic.
This is one of these letters about documentation. My knowledge hasn’t grown by as much as I would have loved, but I read some interesting articles about docs. I want to share these with you.
Teamwork
Hi friend.
You might remember that I told you about my “type”, the INTJ (Architect). Reader Gary wrote in to share his thoughts about that (quoted with permission):
Processes for achieving quality
Hi friend.
So I’ve been busy at my client’s today. I had to implement a sidebar navigation with React. I did something like that a few years ago already and could now redo it for this client. This was great because I could build on my knowledge from the last years. And that’s why I got totally lost in time… I bet you understand. 😉
Last week we talked about quality, and how you could measure it in other’s projects but also your own. Today I want to think about how we can achieve a certain level of quality. But more important: How can we make sure we always achieve this level in our projects.
Quality (continued)
Hi friend.
My brother reads these emails as well, and responded with some interesting thoughts re: quality. Shared with permission:
Aside from hard metrics that are often difficult to install, there’s also a lot of experience involved. I look into details like communication, discipline, timetables and overall presentation of the topic and the approach of the presenter. Does it “feel” right/good/viable or are they just putting on a good show? One major category is the quality & depth of their questions and documentation. If those offer good quality and are well structured, I usually find the rest of it also well produced.
Quality
Hi friend.
If you buy a piece of furniture, like a chair, you can compare it with all the other chairs in the exhibition. You can sit on them and compare how they feel. You get a feel for the wood, whether it‘s cheap or high quality.
How do you do that with code? Once the software is released you are able to compare and evaluate. But before?
Trade-offs
Lazygit
What am I doing?
My freelancing since January couldn’t go any better. I am happy, I am learning and I am challenged. But I already know, that freelancing for clients isn’t everything I want to do. This is, and always was, supposed to be the first step into the “right” direction.
I read lots of articles by other freelancers and entrepreneurs who shared the “why” behind what they do. Today I want to do a bit of the same. Perhaps you’ll find it interesting as well?
Daylight saving time
Did you hear about the European Union polling its citizen about whether DST is really necessary?
Because I thought it’s funny I sent this issue an hour later than usual.
I was wondering what happens with our apps and services, if DST suddenly isn’t “necessary” anymore. The offsets for saved timestamps become invalid?
You get to decide
The Inner-Platform Effect
“The Inner Platform Effect is an anti-pattern that occurs when a software system is designed to be so customizable that it ends up being a poor imitation of the platform it was designed with.”
Matthew has started a new series on anti-patterns in software development.
Why are our estimates off, always?
Formatting dates
Reading Code
_ This is another email I am sending while being happily busy with our newborn._
Two days ago I linked you to an article about Livable Code. Today it’s about reading code. While learning software development I often heard the phrase that you should read other people’s code because it makes you better.
I have to admin, I never purposely did so. Well, one time, I followed through the Rails framework to understand how an HTTP request is handled. But that was the exception. It turns out, I am not alone:
Surprises when starting out as a software developer
_ This is another email I am sending while being happily busy with our newborn._
My first job was as a software developer at Ericsson in Montreal, working with the mobile switching center that handles calls in a cellular network. There was a lot of code controlling call set-up, hand-offs, roaming etc, but I was pretty disappointed to see that it was all done with quite basic data structures and algorithms. The most interesting part I found was the code keeping track of roaming subscribers currently in the system. It consisted of one thousand binary trees, where the last three digits of the subscriber number determined which tree a given subscriber belonged to. To find a subscriber, you picked the tree based on the last three digits of the number, then traversed the tree to find the subscriber. Apart from that, it was pretty much only linked lists or simpler.
Big Nerd Ranch
This is another email I am sending while being happily busy with our newborn.
Sometimes things don’t always go as planned. Code breaks, servers crash, or a product doesn’t work – you know the story.