#begin
The next big topic of this chapter is called It’s all writing. This section will dive into the many kinds of documentation we will have to write as pragmatic programmers. Andrew and David mention that we should treat english, or which ever language you or your company use for internal and or external communication, as just another programming language. The same pragmatic principles apply to english as they would do to your programming language, like the DRY principle. We don’t want to document the same thing twice.
Comments in Code
The first topic is of course comments. We do need to leave comments in our code when applicable and make sure they follow the principles laid out in this book, a philosophy of software design and clean code. Andrew and David mention that we do not want repeat the implementation with our comments so the DRY principle applies here as well. Comments should document the why and the goal of something, not the implementation details. Documenting the implementation details violate the DRY principle.
Andrew and David also mention the fact that good naming is an absolute must. They also mention that names must reflect intent. The example they give is a function called GetData, which in reality writes data to the disk. Now that’s confusing! We’ve talked about this extensively in our discussions about clean code. Uncle Bob has some very detailed rules for naming things. Andrew and David also mention the “Stroop Effect” which is an effect that says the brain will continuously mess up the meaning of things. In the book the example they provide is a very simple one. Get some coloured pens and try writing out the names of colours, however, you are not allowed to write down the name of the color you are currently holding. So when you are holding a red pen and have another blue and green pen, you need to write out the word blue or green with your red pen. This will mess with your brain in a weird way. This is called the stroop effect. We don’t want this to happen during coding because it will introduce some nasty bugs.
David and Andrew do mention that it’s an absolute must that the original writer of a file should leave his name in a comment somewhere. They say that this attaches responsibility and accountability to the authors. Well, this is pretty much antiquated. First of all, source code control systems track this stuff, and second modern software engineering teams have a shared sense of responsibility. We of course want to have some accountability about some code but we should also trust our colleagues to do good work and share the ownership of the code.
Executable Documents
The next topic is Executable documents. This mainly boils down to having documents be updated automatically. So, for example, when you’re releasing some kind of API documentation for the software you are writing you should use a tool like doxygen to automate that process. Once a change is made to the software, the documentation is updated automatically. This can be done really easily with modern tooling like GH actions, or gitlab CI pilelines. From this perspective, documentation is just another view on the code.
What we want to circumvent is the fact that one thing updates, another thing gets outdated immediately. We also want to avoid any manual intervention because we will miss it and the documentation will be out of date with the production environment. That will cause trouble at some point especially when it’s external facing documentation.
Andrew and David mention that we want documentation to be integrated and part of project development. This way the documentation will always be up to date with the project, which is exactly what we want. We want to minimize the amount of work we have to do for each change, so it documentation changes automatically, that’s a win.
Technical Writers
The next topic are technical writers. Up till now Andrew and David have only talked about how we as the programmers should write documentation. But in many cases, there is some team that does the proper technical writing for us. I think that’s great since they actually like doing it. Well, I sure hope they do. David and Andrew mention that we should not just throw our things over the wall and expect the tech writers to do the rest. We should guide them and teach them about pragmatic principles like DRY, orthogonality, it’s just a view and of course automation and scripting. These principles will make their life easier as well.
Print it or weave it
A problem with printed documentation is the fact that once it’s printed it will go out of date soon. Luckily nowadays the documentation of about anything is hosted online and will be hooked up to automation pipelines as we talked about just a minute or two ago. David and Andrew say that sometimes it’s inevitable to have the documentation in different forms like hosting it online but also providing training sessions or presentations about it. So you might encode the same information in some kind of slide deck. Often you might just copy and paste that information over from one medium to another. But there’s better ways to do this. You could use some kind of markup language to simply format the information in different ways, hence the saying; it’s just a view. You could generate the output from some LaTeX document into a pdf or pttx file. I’m not entirely sure how this would work because I expect there to be some degree of duplication somehow but if anyone knows, let me know. David and Andrew also mention to use CSS to restructure information in different way. That however, I do see happening as that’s exactly what CSS is used for right, styling shit. So you could use CSS to format information in a presentation type style or in some summary for example. I’m not sure how this would work exactly, but then again, I’m not pretending to be a CSS expert.
Markup Languages
That brings us to the topic of markup languages. I suppose we are all familiar with a couple of markup languages like HTML or LaTeX. Such languages are used for formatting information in a certain way. David and Andrew give the advice to use such languages, especially for large projects. You can setup some schemes and standards for documentation this way and it makes everything look more coherent.
One important aspect to keep in mind is that the markup language you choose must be rich enough to express the concepts you want. Well I guess this is true and I think most markup languages we have today are able to express whatever information we want. They have greatly evolved since 1999. I especially like LaTeX. It has a bit of a learning curve but once you understand the concepts you can really create about everything. I got introduced to it during my time in university and have used it for many things. For example; my resume is made with LaTeX. It’s easy to maintain and styling is applied automatically. Really easy.
This simplicity can bring documentation to the foreground and avoid it to become a second class citizen. You must treat documentation with the same care as you do with the code.
#end
01010010 01110101 01100010 01100101 01101110
Recent Comments