Working in Google - if you don’t document something, it essentially doesn’t exist

In Google, there is a saying something like “if you don’t document something, it essentially doesn’t exist”. Code, design, Q&A, Bug are all documented in various different mediums or tools. The performance review conducted is heavily relying on these documents to determine one’s performance. The fact that many things are well documented is very good for new hires like me to pick things up. Instead of going to my manager/colleagues to figure things out like my previous job, I can search on internal search engine to find design documents on how a system was designed. A system later on evolves in a documented in the codebase as code change files submission. Each code change files has a link to an issue tracker associated with it to document why code change files was created. The issue tracker contains discussion, which can contains valuable link to other documents. The well-documented-ness is even reflected in the source code. In Google, data structure are defined in protobuf. Protobuf fields are commented, and these comments are good source of truth on how a system works. A protobuf message can generate class, struct, or other types of data structure representation in various programming languages. Essentially, they all have the same semantic defined that is documented in a protobuf message. This makes communication between servers/processors easier. A server can expose a service definition with request and response defined in protobuf. The server can effectively be understood and be called by other servers/processes in any language. Protobuf request and response are well documented, so other developers can come along and understand the server.

Design document is of great importance. When I write design document, I am detached and remote, which avoids being influenced by other distractions that associated with interacting with other people [1]. When I am forced to write down the design, I often find how little I know how my system actually works. Design document is not only to document how something works, it also facilitates discussions among other Google engineers. There is only so much I can know, and I have many blind spots. Having a third eye to look at my design, and gathering feedback from them, can improve my design. Often, a design includes changes to other service which I know little about. In that case, I can dig into the “documentation” like I mentioned previously, and understand how to change. This element in this design doc is uncertain as to how owners of other service feel about my changes to them, and if my changes will or will not break their server, and if my change is semantically incompatible or less elegant. In that case, it is good to include the owner in the discussion, which is done by commenting with “@…” in the google doc. I can ask questions as simple as “does it look good to you” to confirm my change to their service is good to them. I can also comment on myself as a way to remind me things to figure out later as comments like “@me, TODO …”.

Another reason why documentation is important is that I tend to forget things over time, like many people do. The forgetfulness can be even that something I realize like one minute ago, then I forget (Ideas are slippery). But documentation (text, writing) outlives my memory. Before I forget, I document it down, which makes it permanent present in Google. The art of documentation is that I can look back on it, and quickly “remember” how a system I designed works, how a bug was fixed, why did I do what I did, how I performed a certain procedure, what I investigated and found out about. I can use documentation quickly find out some information needed to fix a bug, build a new feature, answer a colleague’s question, and repeat a procedure and so on. In Google, there tools that make me easier to search for documentation, which is even better. To say metaphysically, my documentation is part of my Self.

[1] “For Barthes, Derrida, and Foucault, writing is a better animal than speech because it is iterable; it is iterable because it is abstract; and it is abstract because it is a function not of presence but of absence: the reader’s absent when the writer’s writing, and the writer’s absent when the reader’s reading” from “A Supposedly Fun Thing I’ll Never Do Again by David Foster Wallance.