Christmas reading list and writing tips

Our two weeks of vacation are now over, two weeks of family celebration, and while I was playing video games, my husband was upstair working on C³ as always. Since last time, I continue to insist that he should start writing a description of the project. I believe this process will give his vision a much more precise shape. Two difficulties arose from this: words and scope.

I have this great concept in mind but have no idea if it has a name or if I just invented it!

When starting to write things down, Alex had to find the correct vocabulary to describe what he had in mind. The problem is, there aren’t always words for the concepts he wants to express. Or maybe there is, and he just doesn’t know? Or even worst, sometimes in the world of language designers, the same word have been used to describe different concepts, but he needs one for each of them. He ended up reading tons of papers on programming language, watching conference videos, reading presentation slides, and searching in the dictionary. At some point he may have to invent his own vocabulary, and try to keep away from weird terms such as in Algol-68 (my favorite algol invented term is “incestuous union”, isn’t it amazing?)

I don’t think he found all the answers he was searching for, but he sure made a lot of discoveries that are shaping C³ into something even better. I asked him for a bunch of interesting links so that I can read them myself, and share them with my dear readers. Here they are:

If you have suggestions, either texts or videos, that my husband and I should read or watch, please post them in the commentaries!

How precise should I make this documentation?

Is is very hard to define the exact scope of a first draft documentation for such a large scale project. Code is documentation, the most precise documentation you can hope for, but it is filled with unnecessary details and doesn’t focus on the big picture, so we need words (and/or drawings) to do that. How detailed should the description be and how much should it cover? What is the language syntax, how it works underneath, how it integrates itself with the tools, how it changes the world? He is far from complete in the process of writing so I figure I would write some tips to help him out, tips that could apply for any large scale architecture project.

We have to go back to the goal of this process: refine and clarify the vision. Get down and try to express in words the main aspects of the project, especially everything that makes C³ distinct from its predecessors. What is C³? How does it work? How is it used? But especially, what does make it special?

Having a vision is the starting point, one cannot refine nor clarify what doesn’t exist. Alex has lots of ideas about his project, but he needs to narrow them down to what is really important. This can take the form of vision statements. This method usually have the reputation of a marketing/manager thing but actually, the main goal of these statements is to provide a decision making tool. Testing new ideas against the vision statements allow to see more easily if they are in the right track or not. Since the beginning we have used the three words “flexibility, performance, control” to test lots of the concepts. They have been very useful but is also proved too vague to really lead in the right direction. Many other programming languages could claim to answer to them, while we feel those languages don’t go as far as we aim. I feel that an improved vision statement could probably be a refined version over what we have already been using.

No matter how clear are the ideas, start writing now. Different audiences require different documentation, but we need to be able to write for ourselves before writing for others. Being completely accurate is important when writing for others, but not when writing for yourself. Let the words flow, draw diagrams with tons of overlapping arrows, read ourselves back after a good night of sleep, thrash, re-write, fill the gaps, and start writing again. I believe we will then find our ideas evolving faster than if we had kept them inside our mind.

Priority in writing documentation should be set as in any projects, start with what is the most risky and what gives you the most added value. Describing the little details of something that already exist elsewhere is surely easier, but won’t give you much in return. Efforts have to be put on both the unknown and the major innovations, and they are often intertwined.

Early in the development, better start with the big picture, and refine each section in the next iteration. For this, structure is the key. The exercise of structuring the documentation might have an influence on how you will structure the implementation later on, and it might be easier to do this with words than code. Breaking down the project in parts, then breaking each of these into smaller items will help you find out what is already defined, and what is not. We have never done anything like C³ before, very few have come anywhere close, and so it is very hard to describe and evaluate the project. But if we split it into smaller items, chances are that many of those elements are similar to things that we have encountered before and therefore are easier to describe and represent less risk. Then we can get a better view at the unknown, split in smaller sized pockets, more manageable this way.

How to know what is important to describe in the “how does it work?” section? Before anything else, we need a good conceptual model¹, or in other words, how the system needs to be understood from the outside. This description does not need to be complex and exhaustive. On the contrary, the simpler, the better. The code shall be the deep description of how it works inside, the conceptual model is used to get in touch with the actual goal: that C³ be used by actual people. Talking about this, my husband suggested that he should start writing use-cases, I believe this is the right track.

Back to the pillow talking

I love staying in bed in the morning, and talk with my husband for hours, programming language design being our favorite conversation subject. So two weeks of vacation gave us much more opportunity to do this than usual. He was thrilled with the unification of static and dynamic polymorphism, but now he feels that the unification of imperative and functional programming has even more potential. I love to see him as excited as he is about those things, and all this reading and writing is stimulating even more.

¹ I’m borrowing the term “conceptual model” from “Design of Everyday Things” by Donald A. Norman. The author describes how important it is for the user to have a mental model of how things work inside in order to use them correctly. I deeply recommend this book even if it is more than 20 years old!

Leave a Reply

Your email address will not be published. Required fields are marked *