Another session of Top Performer is underway, and one of the goals of the early lessons is finding a skill that is important for success in your career. That has me thinking about skills for programmers. Today I’m going to focus on one particular skill that is critical for programmers working on a team, and becomes more critical as you work on larger projects.
I wrote about a few different skill categories in Skills for Programmers. If you’re a new college graduate starting a full-time job, you might have strong algorithmic problem-solving skills, knowledge of Computer Science fundamentals, expertise in a few specific technologies, and good work habits. Depending on your background, you may even have some of the soft skills required for success at a software company. But what new graduates generally don’t have is experience working on a large codebase that a team of programmers has built up over several years.
When you’re building a small project from scratch, technical questions can be answered through a Stack Overflow search. You still have to think about timeless software engineering questions like good design and whether you’re building the right product for your target audience. But you can rely on others who are working with the same technology to get you unstuck.
When you’re maintaining or enhancing a large software system as part of a team, it’s not enough just to know the technology you’re working with. You also have to know the details of the specific system you’re working on. As I wrote a few weeks ago, that means you have to figure out how to learn from local experts.
If you have a general programming question, find the answer on Stack Overflow, and later forget the answer, you can always find it again. I do that all the time. But if you forget an answer that you got from a local expert, you have to go back to that expert to get it again. That’s an inefficient use of a scarce resource, and it might make your expert grumpy. You want to make the best use of your local experts or, if you’re the expert, ensure that others make the best of your time. You can do that using the skill I’ll be exploring today.
A Useful Skill
Google’s mission is: “to organize the world’s information and make it universally accessible and useful.” Think about the information that would make your work easier, but which no one has yet organized into an accessible or useful form. If you can learn to find, organize, and share that information, you can make a difference to your own productivity and the productivity of your team. Since you’re dealing with specialized information about your own project that may have limited documentation, a little effort will go a long way.
The number one goal for organizing your technical information is being able to find answers when you need them. You could try to solve this problem by constructing the perfect hierarchy of topics for your information. But as web sites have learned and re-learned over the past 15 years, a good search engine beats every other type of site navigation, no matter how carefully designed.
A large part of the magic of web search comes from the feedback that search engines get from their users. A user submits a query, the results page appears, the user selects one of the links to click on, and the search engine gets a tiny bit of information about link relevance.
Since you won’t have billions of people clicking around your project documentation, you won’t be able to use techniques that rely on aggregating a large number of tiny clues. But you can still help make search more effective by naming pages accurately, including relevant keywords, and writing complete descriptions of the features you’re documenting.
If your project has no good documentation, you can start with almost anything: a list of useful links, a FAQ, advice for setting up a development machine. Then once you have the basics covered, you can come up with topics that need to be explained in more depth. By writing up what you know, you get a couple of benefits:
- Clarify a topic to yourself by organizing information about it and explaining it to others in written form.
- Expand your collection of information so that people such as yourself find the answers they’re looking for when they do a search.
While you may not have the Googlebot crawling your private pages, there are tools that can make it easier to organize and find your information. I like OneNote. Evernote is another popular option. The key is to use a tool that makes it easy to add new pages, and provides fast full-text search while allowing enough hierarchical structure that you can browse around if you know what you’re looking for.
What’s a useful complement to a document describing how a software system works? Automated tests that enforce that description, and notify developers when they attempt to change an assumption.
When you find yourself documenting something about your system, consider whether you should also write a unit test that covers the same area. The documentation is a useful summary, and is accessible to people who aren’t as comfortable with code, while the unit tests provide working examples in addition to the design and refactoring benefits of automated tests.
A Project Idea
If you want to improve your information organizing skills, you’ll need practice. A good way to structure your practice is with a project. Here’s an idea for one:
- Do your regular work, whether it’s a software job, school, or a side project.
- When you need to look something up, don’t just find the answer and move on. Take the time to write a brief description of your findings in your note-taking tool of choice. Use keywords and sufficiently detailed descriptions that you’ll be able to find it in the future.
- Make a habit of searching your growing information stash in addition to your usual sources, like Google or your company Intranet. If possible, put your notes somewhere that people in your organization (or beyond) can discover.
- When you find an answer in your information stash, ask yourself whether you could have found it faster or more easily. Can you add keywords or metadata? Should you move it to a more intuitive location?
A project like this can build some good habits and skills and as a bonus, you’ll end up with a well-organized reference to the project you’re working on.
(Image credit: Matt Davis)