October 2016 | Spinning Code

Documenting your work

Programming books — Your documentation does not need to look like this.

Early in my career I spent a lot of time as the only technical person on project, and therefore believed that I didn’t need to document my work carefully since I was the only person who had to understand it later. It turned out that if a project was back burnered for a few months the details were pushed out of my mind by the details of eight other projects.

Any project that takes more than a couple hours to complete involves too many details for most people to remember for more than a few days. We often think about project documentation as something for other people – and it is – but that other person may be you in six months.

I learned to start keeping notes that I could go back to, those notes would turn into documentation that I could share with other people as the need developed. My solutions were typically ad-hoc: freeform word documents or wiki pages. For a while I had a boss who wanted every piece of documentation created by IT to fit a very predictable format and to be in a very specific system. It took two years for him to settle on the system, process, and format to use. By then I had a mountain of information in wiki pages that documented the organization’s online tools in detail, and no one else is IT had anything substantial. It was two more years before the documentation of other team members got to be as good as my ad-hoc wiki.

That’s not to say a rogue solution is best, but the solution that I used was better than his proposed setup for at least three years. That experience got me to think about what makes documentation useful.

Rules of thumb for good project documentation:

Write up the notes you’d want from others when coming into a project: think of this as the Golden Rule of documentation. Think about what you’d want to have if you were coming into the project six months from now. You’d want an outline of the purpose of the project and the solution used, and places they deviated from any standards your team normally uses. You’ve probably read documents that are explaining something technical to an expert that are hard for anyone else to understand – if I’m reading the documentation I want to become an expert, but I’m probably not one already.
Keep it easy to create and edit while working: if you have to stop what you’re doing and write your notes in a totally different environment that your day-to-day work you will not do it. Wikis, markdown files, and other similar informal solutions are more likely to actually get written and updated than any formal setup that you can’t update while doing your main work.
Document as you go: we all plan to go back and write documentation later and almost none of us do. When we do get back to it, we’ve forgotten half the details we need to make the notes useful to others. So admit you’re not going to get back to it and don’t plan to: write as you go and edit as you need.
Make sure you can come in in the middle: People skim project documentation, technical specifications, and any other large block of text. Make sure if someone has skipped the previous three sections they can either pick up where they left off, or give them directions to the parts the need to understand before continuing.
Track all contributions: Use a system that automatically tracks changes so you you can see contributions from others and fix mistakes. Tools like MediaWiki, WordPress, and Drupal do this internally. Markdown or text files in a code repository also have this trait. Avoid solutions like MS Word’s track changes that are meant for editing a final document not tracking revisions over time.
Don’t fear editing: follow the Wikipedia community’s encouragement to Be Bold. You should not fear making changes to the team’s documentation. You will be wrong in some of what you write, and you should fix any mistake you find – yours or someone else’s. Don’t get mad if someone makes a change that’s not quite right, revert the change or make a new edit and more forward.
There is always an audience: even if you are the only person on the project you have an audience of at least your future-self. Even if it feels like a waste in the moment having documentation will help down the road.

Remember even if you are working alone you’re on a team that includes at least yourself today and yourself in the future. That future version of you probably won’t remember everything you know right now, and will get very annoyed at you if you don’t record what they need to know. And if the rest of your team members aren’t just versions of yourself they may expressed their frustration more directly.

Why I think pushing only STEM is a problem

Over the course of this week I needed to be conversant in PHP, MySQL, Linux, Drupal, search tools, herbal remedies, online education tools and strategy, women’s health, men’s health, canine health, dental health, health insurance, public media outlet fundraising, online advertising, email, open source technology, open source movements, cyber security, physical security, national security, state and national politics, disaster response planning, disaster response fundraising, coffee, vegetarian ethics, economics, retirement planning, videography and photography, child rearing, fiber arts, baking, and a few other topics.

Last week I talked a bit about the things I got from my liberal arts education that made me a better developer. There I focused mostly on the positive side of the argument: why non-stem course work is important. Now I want to flip the coin and talk about why our constant push to have more people graduating with STEM degrees is bad for the country and the economy.

No, I didn’t learn about all the topics in the opening in college – in fact much of the information I gathered in college on many of those topics (particularly things related to technology) is now at least partially out of date. But I spent four years learning how to learn and developed a base of skills in several disciplines that makes it easier for me to adapt to change and new areas of interest.

In 2016 the path to most high paying jobs runs through college. And the majority of people who go to college earn more than they would have if they hadn’t gone to college. But if we talk about college as being all about our work and pay we miss the main point of a good education and we ignore the fact that our education system should help mold engaged citizens not just good workers.

The push to graduate students to be “workplace ready” in engineering and technology (people calling for STEM education rarely care about science that can’t be applied to engineering new technologies and pretty much never mention math) is short-term thinking. That kind of educational model frees companies from having to train new employees while weakening their long-term workforce and our democracy. Our education system, high school and college in particular, needs to be helping kids become productive members of a society none of us can fully predict. To thrive in current and – more importantly – future America we all have to adapt to constant technical and social change. You cannot teach kids in school how to actually handle the situations that don’t exist yet, so we need to be teaching them how to learn so they develop skills as they need them.

Companies go looking for the employees of tomorrow, but not of next year, or of five years from now. They complain that younger workers don’t want to put in time at low-level jobs while refusing to provide training to help those new workers advance. What we get all too often are people who are good-enough to do the work of today and tomorrow, but never get better.

When I first wrote code for work, I was terrible. I got better because I was allowed to fail and learn from my mistakes. If you’d judged my college program on that first project, you’d call Hamilton a fraud. If you judge them by my ability to adapt, change, and improve, you’d rank Hamilton a top school as most rankings do.

College should be part of an education meant to prepare people for a life that will be unpredictable and varied. It should part of an education built around showing kids as much diversity of thought as we can:

Kids need art courses because art helps us all see the world fully and because developers need artists on our teams to make our projects successful.
Kids need to learn history because history matters – when our society repeats mistakes because we don’t understand our own past we all lose.
Kids need to learn math and science because we need them to understand how the universe works and that facts are not something that change when it is politically convenient.
Kids need to learn to challenge ideas they are taught because even the best teachers will be wrong sometimes.
And kids need to play because it’s good for their bodies, minds, and souls.

I work for a company that develops software every day of the week. There are ten of us whose primary job is to write code, so we need great developers. But there are 30 people at the company which leaves twenty of us who do things other than write code – we need great designers, writers, account managers, and more. Yes, they need to understand the internet and the tools we use at some level, but more importantly they need to understand how do their part in helping our clients be successful so that our company can succeed.

And at the end of the day all thirty of us live in a democracy, and in November all of us should be casting informed votes up and down the ballot for people we think will do the best job. The artists will need to understand the tax policies, and the developers will need to understand the impact of social program proposals. We don’t have to agree, but we all need to be prepared.

If you want a deeper argument about the importance to the world of people with a broader understanding of many topics check out Former Bennington College President Liz Coleman’s Ted Talk.

What I learned by getting a degree from a liberals arts college

I have a degree in Computer Science, with a minor in Economics. But I earned that degree at Hamilton College, a traditional liberal arts college. That meant I was forced (now students there are just encouraged) to take classes in a variety of disciplines. I went to Hamilton in part because they offered degrees in Computer Science and History, and I was interested in both fields. In addition to the courses required by my major I took classes in history, religious studies, philosophy, art, and more. And I learned critical skills for work and life because I took those classes.

Two hand made mugs — Making these mugs made me a better developer.

Ceramics and pottery taught me to be a craftsman, accept critical feedback, and admit failure. For all the courses I took in college, the time I spent in Ceramics and Pottery studio taught me more about how to be good at what I do than any other course work (including CS). Basic pottery is a craft that doesn’t allow you to save a piece once you’ve made mistakes. If you are making cylinders the walls aren’t straight throw it away and start again. My professor in those courses set very high standards and pushed us to meet them through brutally honest, but helpful, critiques. He taught me to appreciate honest feedback, and to be skeptical of my work before showing it others. In those courses we had to do good work, recognize our weaknesses, and hit deadlines.

History taught me to care about communicating. Between the courses I took, and dating (and eventually marrying) a history major (now professor) I came to understand how important it is to communicate well in speech and in writing. I started this blog in part because I wanted to make sure I was spending more time writing to help maintain those skills. I frequently find myself in meetings having to explain highly technical issues to non-technical clients and colleagues. Knowing how to adjust to my audience, without insulting their intelligence, is a critical part of my day to day work.

Religious Studies and Philosophy taught me to make a well reasoned argument and express the ethics of my position. Religious Studies and Philosophy both require you to make arguments based primarily on the strengths of your ideas – you can’t research your way out of a bad concept. If you cannot assemble a well reasoned argument you leave yourself open to easy counter attacks. When you work at a nonprofit you often are building your ideas and your explanations from a mix of the facts of the issue, your worldview, and the assumptions you are forced to make because no one has all the information they really need.

Economics taught me how to view the world through the lens of money and trade. While I don’t think it’s the only, or even best, way to view the world it is a very important worldview that dominates the news and political spaces. Understanding the strengths and weaknesses of economics as a field helps me think about plans put forward by various politicians. It also helps me think about how the companies I work for function, and helps make sure internal systems and plans I propose have a strong business case to support them (and because I learned to throw things away in ceramics I also know that when the case is bad to stop and try something different).

The most important skill I have is the ability to learn new skills. Since I graduated from college the technology I work with every day has changed several times. I’ve had to learn tools, techniques, and strategies that didn’t exist when I was in college. And my career has evolved through multiple employers, disciplines, and areas of expertise.