An introduction to the C4 model

The C4 Model for Software Architecture
(Image source: The C4 Model for Software Architecture)

This week, I was introduced to a new (to me) methodology called the C4 model. Now, in this context, C4 does not refer to the high explosive. In this case, C4 refers to a development methodology. Mostly, it refers to software development, but it has other applications as well, and that includes document development.

As part of my indoctrination into this methodology, I was provided this link. So far, it looks like an interesting read. I’m still reading about it, but here’s my understanding of the methodology thus far.

First of all, C4 stands for context, containers, components, and code. Think of it as looking at something at four different levels, from the top level (context) that shows the big picture, all the way down to the most minute detail (code).

The top level (context) refers to the big picture. Using maps as an example, here is a map of the United States — for purposes of this example, the big picture. You’ll notice that I drew a black box around New York State, which indicates the next level to which I will zoom.

If we want to drill down to the next level (container), a state would be the next logical level. So for the next map, I’m drilling down to my home state of New York. Again, I’m drawing a black box around the area to where I will drill down next.

A city or region is the next logical step (component). Let’s drill down even further, this time to my home city of Troy. Again, I’m drawing a black box around the next level to which I will zoom.

The bottom level of this methodology (code) shows the minute detail. For personal privacy reasons, I’m not using my home location, so instead, I’ll use one of my favorite establishments: Brown’s.

You’ll notice that I did not draw a black box in the last illustration; this is because we are at the lowest level in this model. I suppose if I really wanted to get granular, I could drill down into building floor plans, but for the purposes of this example, I think the point is made.

From how I understand it, the C4 methodology appears to be used for diagramming and documentation. It addresses a shortcoming in many technical diagrams in which they can be confusing and difficult to follow. C4 addresses this by showing how components relate to the big picture.

While I haven’t (yet) come across this in my reading, I want to note something that I think is important. When I captured the maps you see above, I thought it was important to highlight the context to which each level was related. If you look only at the bottom code level, you only see a building and a street (although I did make it a point to also capture the street name and route number). If you don’t know what city or state this place is located, then this macro level is likely useless information. The same is true for technical documents. Each small piece fits into a larger puzzle. If you don’t understand how the puzzle piece fits, you don’t get a sense of how the piece relates to the rest of the puzzle, and it becomes confusing and hard to follow.

As I said, I’m still reading about this, so I’m not yet sure what additional intricacies about the methodology I need to learn. Nevertheless, the concept does sound interesting, and I’m looking forward to learning more about it as I improve my skills as a technical communicator.

Some links, for your (and my) reference:

A picture is worth (writing) a thousand words

On a recent project in which I was documenting an application, I found myself hitting yet another case of technical writer’s block. I sat in front of the screen, staring at the application — sometimes, for hours — and came to the realization that all I was doing was blankly staring at the screen. I tried different techniques to stir up ideas as to how to tackle writing the documentation, but no matter what I tried, the words just wouldn’t come. Even just trying to figure out a document structure — never mind actually trying to describe the application — was proving to be elusive.

It was at that point where I decided to give up on trying to write a description of the application functions and turned my attention to grabbing screen captures. I went through the application’s menu structure, built a document heading hierarchy based on it, and started working on the application images I’d just captured. I took the time to clean up the images, including altering them to eliminate any client or user data (replacing them with “dummy” data), and formatting them for my document. Once I was satisfied with the result, I inserted it into the document, proceeded to the next screen capture, and repeated the process.

A funny thing happened during this process. First, I found that my document was expanding in content. Granted, it was mostly graphics, but it was, nonetheless, content. Second, I’m finding it easier to come up with ideas for descriptions and text content. Third, I’m no longer blankly staring at my screen; I’m finding that I’m actually productive. Finally, I’m finding myself having fun with the process!

This is not the first time that I’ve performed this process while writing a document. Indeed, I’ve often worked on documents in which I found myself in a writing rut, shifted gears to work on graphics, and discovered the spark that I needed to write the text.

It’s an age-old saying that “a picture is worth a thousand words.” Most often, this phrase is geared toward the perspective of the reader. However, what is not as appreciated is that this clichĂ© is applicable to the document developer as well. If ever you find yourself in a writing rut, try working on the graphics. It might just be enough to spark ideas and get you out of the rut.

Stop treating technical writing like a second-class citizen

File this under another technical writing frustration.

Imagine that you are an application developer. You finish an app for a client that you send for review. The app is clearly labeled as a “testing version,” and includes source code (yes, I know this last part doesn’t happen, but just humor me for a bit). You are meticulous with your updates, keeping track of version control and changes. You ask the client to review it and get back to you. You move on to work on other projects, forgetting about the request. A few weeks later, you remember the project, and realize that you hadn’t heard from the client. You contact them to follow up, and are chagrined to learn that not only are they using your test version app in production, they also changed the source code for what they need.

Sounds outrageous, right?

Now, substitute the following words and phrases: “technical writer” for “application developer,” “document” for “app,” “draft” for “testing version,” and “MS Word” for “source code.” Welcome to my world.

This is an actual workplace scenario that happened to me a while back, and I was reminded of this recently when the same client asked me for an MS Word version of a document (that I had sent as a PDF — I was never, ever going to send them an MS Word doc again) so they could make changes. I refused, and I told them why.

The client in question had taken my Word document — the one that I had asked them to review — and I will add that I had DRAFT stamps all over it — and were using it in their production environment. Not only that, they had made changes to it for their purposes.

Well, I found and incorporated their changes, removed the DRAFT stamps (they were obviously okay with the document), and slapped a version number on it.

I also told myself that I was never sending them a Word document ever again. They were only getting PDFs from me.

I’ll be honest. What the client did absolutely pissed me off. By “changing the document for their needs,” they completely compromised and undermined my work, they blatantly stepped on my toes, and they completely disrespected what I do.

Most of the clients I work with aren’t like this, which is why I usually don’t have a problem sending a Word document (with DRAFT stamps) out for review. Thankfully, the scenario I just described is, in my environment, the exception, not the rule. Sadly, however, there are still too many people who hold this attitude that documentation is just a side item, and treat it like a second-class citizen.

This is one of the things that drives me to do SQL Saturday talks. This is why I do my presentations. This is why I rant about poor treatment of documentation. And this is why I actively tried to leave a job.

I’ve said this time and again. Document development needs to be treated in the same way as software development. The life cycle, including version control, is no different. Not doing so undermines what documentation is. It’s a critical function in application and professional development. And as someone who has had experience in both application and documentation development, I demand: stop treating documentation like a second-class citizen.

First drafts are ugly

“The secret to life is editing. Write that down. Okay, now cross it out.”

William Safire, 1990 Syracuse University commencement speech

“No thinking – that comes later. You must write your first draft with your heart. You rewrite with your head. The first key to writing is… to write, not to think!”

William Forrester (Sean Connery), Finding Forrester

“Just do it.”

Nike

I will confess that this article is a reminder to myself as much as anything else.

Raise your hand if you’re a writer, and whatever it is you’re writing has to be perfect the first time around. Yeah, me too.

How many times have you tried writing something, but in doing so, you hit a wall (a.k.a. writer’s block) because you don’t quite know how to put something in writing? Or how often have you written a first draft, only to take a second look at it a second time and say, “what a piece of s**t!”

(And speaking as someone with application development experience, this happens with writing code, too. Don’t think that this is limited to just documentation. This is yet another example of how technical writing and application development are related.)

Someone (I don’t know whom) once said, “one of the stupidest phrases ever coined is, ‘get it right the first time.’ It’s almost never done right the first time!” In all likelihood, you need to go through several iterations — review, editing, rewriting, etc. — before a draft is ready for public consumption. It’s called a “draft” for a reason.

The fact is, nobody has to see what you write the first time around. If you’re trying to get started on a document, just write what’s on your mind, and worry about making it look nice later.

Playing in the sandbox is important for documentation

While working on a user guide, I realized that I had administrative rights to the application I was trying to document. That was all well and good, except that I was trying to write a non-admin user guide, and I needed to know how someone who didn’t have admin rights saw the application. Fortunately, one of my co-workers sent me an application URL and a testing user login I could use that simulated exactly what I needed.

That brings me to today’s article. Many application development environments make use of a sandbox, or some other development, environment where a developer can play to their heart’s content — that is, some place where someone trying to test or develop applications can play with the app without having to worry about breaking anything important. That same testing environment is just as important for a technical writer.

Much of my work as a technical writer involves putting myself in an end user’s shoes. I’ll often go through an interface and document the steps a user might use, what a user might see on the screen, and the effects of certain buttons and links. One of my most frequent questions when I work on documenting an application is, “what happens when I click this?” After I do so, hopefully my next response isn’t “oh crap!”

This is why a tech writer needs access to a testing environment. Like application developers who need to test within a safe environment, a person documenting the system needs to be able to document the system and be able to do so knowing that (s)he won’t adversely affect the application by playing with the system.

I wrote previously that a tech writer can help an application developer, and vice versa. Indeed, the tech writer can function as an in-house QA analyst. In order to write good documentation, the writer needs a realistic environment in which (s)he experiences what an end user might see. Having a sandbox environment in which a writer can “play” provides exactly that type of environment. As an added bonus, not only does this allow the tech writer to produce better documentation, it allows that person to provide feedback regarding the application, which ultimately results in a better application.