Book Review: Apprenticeship Patterns — Guidance for the Aspiring Software Craftsman

Learning the writing (or software) craft doesn’t have to be by yourself

A book review by Robert Delwood, A Lead Programmer Writer

Authors: Dave H. Hoover and Adewale Oshineye

O’Reilly Books (https://www.oreilly.com/library/view/apprenticeship-patterns/9780596806842), 137 pages

If school prepares us to enter our careers, it does little to prepare us for developing those careers.

Apprenticeship Patterns: Guidance for the Aspiring Software Craftsman looks into taking those first steps in a career by treating the profession as a craft. Yes, the book is titled for software engineers, but overlook that — just ignore references to software (“guide for the aspiring craftsman”). Replace developer with writer as you read it. The practices are the same for technical communicators (or any craft, for that matter), and there aren’t many books like this specifically for writers.

The authors, Dave Hoover, psychologist turned developer, and Adewale Oshineye, another developer and project manager, fill in an important gap in this craftsman approach by providing additional, low-level information. They focus on patterns, or rather, common workplace problems with common solutions. As you assemble patterns, distinct paths form. Following those paths turns into a journey, from apprentice to journeyman and finally master craftsman. But first, examine the set of patterns for each step.

As the title implies, begin by being an apprentice. Embrace it. Start with an “empty cup.” That is, know that you don’t know, and use that to your advantage. Too many writers starting out act like they are experts, and actually resist being taught anything. I’ve seen writers interrupt developers in the middle of their explaining a concept with “I know that.” No, no, you don’t. That writer is not going to do well in this role.

Learn to do one thing expertly, such as writing APIs for developer documentation, writing procedures for end users, or explaining technical concepts in white papers, and become known for that skill. Teams are more comfortable with members who have actual skills, not just the promise of skills. Always have the attitude that there is a better, faster, smarter way. Find those who know. The company should provide that environment or at least have those resources available, but ultimately, your task is to identify relevant resources and use them to your career needs. As your portfolio and reputation grow, it’ll be easier to move around.

That gets you ready for “the long road.” Accept that you’re learning a craft and that only Hollywood has overnight celebrities. That means staying focused on your craft and not creating art. No one’s heard of a starving craftsman, just starving artists, and for a reason. Craftsmen create something people need. You’ve mastered a few important skills and moved up in the company. The important aspect here is that as you reach out to a greater community, you realize that there are plenty of people who are more skilled than you and who are still learning. Learn from them.

Gaining textbook skills or collecting certifications isn’t the point anymore; it’s applying all this knowledge in practical ways. Along the journey, you need to watch out for your best career interests and make sure that what you’re doing is what you want to do. For example, many get lost in promotions that lure them away from what they like doing, whether that’s programming or writing.

Finally, don’t underestimate perpetual learning. This is the key to the long road. Take time to practice, even if your job doesn’t seem to allow it. Learn new skills or apply existing skills in new ways. Along with practice comes failure, but don’t let that discourage you. Stay positive by creating a private time or area and start sample projects. Write procedures in a new way, or look at some new software to solve a problem. The point is to have breakable toys in a controlled environment.

The six chapters, 137 pages, and 31 patterns detail the journey. Although titled for apprentices, messages apply to all levels, whether directly or indirectly. It’ll help in working with others. It’s also a good reminder of skills and practices. Personally, I’ve seen too many in the industry simply stop learning after a title or job promotion. Writing is a craft because it’s not a science. We can codify the procedures to be a good writer, but reaching that goal still depends on skills. Skills doesn’t just mean the writing talents of one person but the collective set of everything to create a product, including learning from and teaching others.

Being good or even the best may not be enough. Taking a lesson from history, Antonio Stradivari is considered the best violin maker of all time. Yet, when he died, the secrets died with him because even his own sons couldn’t make the quality instruments that he had. The genius failed to pass his skills on. His apprentices were described as “excellent but no more than that.” They also failed because they should have pushed to learn what Stradivari knew.

Robert has been a programming-writer for more than 15 years, specializing in API reference guides and developer documentation. He believes that automation is necessary for communicators to thrive, and spends much effort evangelizing that message. Technology for technology sake is not the point, but rather the selective application of the right technology.