Creating developer content

The best developer content comes from pulling together all of the expertise and institutional knowledge within an organization, combining it with community experience of technologies and workflows, and making it usable. How is it that, so often, the soul of the technology is lost in the finished product? Is there a model of content production that could amplify the power of a technology product and sustain admiration for how it solves a problem?

Organizational expertise

In startups, the first content created for developers is usually an interface specification. Without this content there is no interface. Without this programmatic knowledge, discovery is a matter of querying and guessing. Engineers know this and are ready to document their programming interfaces at the source.

The next content often developed in the startup comes from a product manager. This manager should know the market, the user, and has set the requirements for the engineering team. They also have presentation skills that allow them to create content. This content is often limited to the system required by the product manager, however. Their experience is in the product, not in usage workflows.

Often, sales engineers and professional services folks are working away unbeknownst to colleagues who want to raise the visibility of internal expertise. They have a lot of expertise. For a couple of reasons, this knowledge does not translate into content. One reason is because they are so busy creating collateral for individual customers. An even more insidious misunderstanding is behind this fallow knowledge: a concern with leaking intellectual property, trade secrets, and proprietary processes, all of which should not be given away for free.

When sales has a need, marketing collateral is generated. While this collateral might provide technologists with enough information to make a purchase recommendation, it is often devoid of substance and can promote vaporware. The marketing is the message.

And thus comes the call for support staff to develop their knowledge base and produce user documentation. These folks are on the front line of customer feedback. They create just in time content to solve the community’s problem. They interface internally in order to get gnarly questions answered. And they know how to develop and maintain customer relationships. The flat architecture of a knowledge base allows for discoverability if it is exposed and optimized for search. But this knowledge is on-the-go, just-in-time, often ad-hoc, and rarely designed within a context.

Finally, an organization will add technical writing resources. Sometimes, especially before a need-to-know mindset solidifies silos of information, the writer might even be given access to all of the mish-mash of content now floating around the organization. At that point, the content is pulled into a management system, enhanced with metadata, turned into consistent procedural and other content types, and edited to reflect the organization’s professional voice and tone. This content often contains the ghost of expertise in a polished and more consumable manner. But deep engagement with the technology is often lost in the cursory instructions and tier-0 recommendations produced.

Specialist first—but what kind?

In modern software development, the use of clear coding conventions, commenting, and version control are considered standard practice. Every software engineer is familiar with this standard practice, since Donald Knuth’s “Literate Programming” book came out in 1984, or by the very latest, with Robert C. Martin’s “Clean Code” book, published in 2008. And the drive toward open source could not have happened without these practices. Open source, coincidentally, played a significant role in improving technical documentation standards, because contributors knew good user-centric content was a key factor in project adoption. Design thinking, as well, shifted the focus from pure technical accuracy to a more user-centered product.

All of these factors drove a great amount of quality content to the internet, with a significant amount of resources invested in its production. Oftentimes, this content was given the in-depth attention of the product experts and early adopters who had domain knowledge. Development cycles were taken up with writing documentation. The published product was highly reliable, meticulously prepared and curated to meet the highest standards of quality. Because subject matter experts were involved (and not just interface developers), the content not only imparted knowledge but also enriched the understanding of the subject at hand.

So should a startup begin their content journey by devoting the highest resources to publication? Well, yes and no. This method of knowledge extraction has a proven success record. But there are more efficient, cost-effective ways of extracting knowledge. Assume an organization has some source of knowledge: some history of vision, design, architectural decisions, validation... Then knowledge extraction specialists, such as content engineers, can leverage that knowledge using techniques such as:

• information architecture
• information metadata creation and management
• taxonomies and knowledge graphing
• data extraction, aggregation, cataloging, classification
• content infrastructure
• content pipeline automation

Note the big mistake a startup often makes is to hire a content strategist first. This is because the money starts flowing to marketing and sales folks. They have the budgetary influence and an urgent need: explain our offerings or folks won't know they want it. Their understanding of content, however, stops at a cursory level of a technical buyer. While this target audience may have domain knowledge of their vertical, they do not need details required to complete successful, production-quality output. The content strategist is usually hired to get everything in the right structure to walk a visitor through offerings and sales funnels. There’s a faulty overloading of the term “content”, here. (Due to an interesting history of market forces, content strategy has not become a corollary to technical strategy.) There are exceptional content strategists whose hire may result in a worthy ROI, but they are usually hired as marketing content specialists. Their expertise is not in developing a framework for the extraction of knowledge for reuse.

Bootstrapping content engineering

In San Francisco, we have a lot of four-way stops instead of lights with long wait times. It is one of the subtle environmental variables that impacts the way we treat each other. One of the byproducts of this is that you have to look at any driver you encounter to anticipate their next move: did they arrive at the stop before I did? Will they go? Will they wait for me? There are rules of the road, but right of way is a mixture of feedback loops and reciprocity. I explained this to a driver new to the City who wasn’t using their turn signals. I went on about the dance of traffic, the intimacy of community, the consensual engagement in courtesy during this moment of pause in an otherwise hectic day. When I finished, their response was: “Well, I just don't want people to know where I’m going.”

OK, let’s presume the startup will succeed—because otherwise, what’s the point? You may have heard developers say something along the lines of, “I’m going to write this code for the future me, who will be coming back in two years to fix a bug.” Whatever knowledge we produce today, presume someone will be returning to it in a couple of years. If every individual knowledge producer had that mindset, a lot of foundational structure would become institutional knowledge. And that’s basically the culture you want to nurture from the first day of your startup. All individuals in your organization should know you’re going to succeed—and continued success means preserving knowledge.

Operationally, you’ll want to set up some knowledge-preservation practices, even before you hire someone to pull together all of the expertise and institutional knowledge. Here are a few examples of best practices:

Transparency, by default

If your startup is based on an idea that can be easily pilfered, go back to the drawing board. If you’ve hired someone, you should’ve vetted them and afforded them a working-level of trust. If you have read this far, you’re likely building an organization with a foundation of transparency and honesty. You may not know this is in the tradition of utilitarianism and the plain-speaking people of early America. And further reading on this tradition may inspire you (with its tenets of simplicity, fair pricing, community engagement, quality and longevity, ethical sourcing, environmental responsibility, customer-centric approach, employee well-being). Whatever your values, make sure to operationalize your values in all of your content production.

For example, if transparency is important, have an open-source mentality internally, even if your organization is still in stealth mode. Discoverability tools are built into most content generation systems (like Google Docs or Confluence). No matter what role that person is fulfilling, if they are seeking information in your organization, they should be able to find it on their own. This means making sure the internal content is set up in ways that help people discover it and its metadata. For example, in Google Docs, make the default for all documents set to general access for the whole organization. Make it searchable, with commenting ability (which provides the reader with ability to view history).

Implement skills-based access

One of the most pernicious practices I see at engineering firms is to silo their code. This, of course, is because it’s precious and being protected from damage or theft. But making access based on roles does not ensure against these problems. Access to technical information is critical to those who are adjacent to engineering, including anyone who has the ability to generate technical collateral. Their access to technical details should be based on their abilities, not the department they’re in. Of course, organizational access is roles based. So create a role specifically for those who need read access to technical sources and be liberal in adding individuals to it.

Keep context (stop using email)

Slack or other messaging apps retain institutional knowledge for the general contributor. Practically, email preserves individual knowledge for those on the thread, is inaccessible as soon as they leave, and is not discoverable to those who come after. Final policies and procedures can be codified on a wiki, but the bulk of conversations that explain the when, why, who, and how, are happening everyday in messaging apps. This content is available for future discovery.

Schema & templates upfront

Look at any good content on the internet and you will find a solid example of metadata: when it was written, for which version or SKU, a descriptive title, by whom it was written, a summary or introductory paragraph providing context and narrowing the audience, and callouts, references, and links to related content.

Don't be afraid to set up a schema, up front, for all content sharing. At the start, just guarantee that a document has:

• date
• subject or feature name
• title
• byline
• summary
• status (draft|final|approved|superseded by...)

Create a template or boilerplate section. Use it, share it, ask that revisions include it. Before you know it, a large amount of your institutional knowledge will be rich fodder for future content automation.

Write in Global English

You don’t need a complicated style guide or voice and tone brief. But socializing a few Global English practices from the start will keep the vision that your organization’s knowledge will be shared internationally, and make it cheaper to do so down the road.

Begin a knowledge graph

Even an abandoned knowledge graph can help future collaborators understand what came before: why was this feature designed with that model? How did two systems work together at first? Which code name was the precursor to which product name? Somewhere in the organization should be a graphical representation of the important components of the vision and the results. Have fun proposing an ontology, like the sub-sub-librarian in Moby Dick caught, but don't get caught in constructing perfect taxonomies.

Knowledge graphs can be fed to LLMs. LLMs can generate them. And iteration of both ML and human curation can improve the quality of your content.

Summary

Operationally, the goal is to preserve expertise so that knowledge extraction specialists can leverage the source wisdom when they streamline the content creation process. Shift your first content focus from marketing content to developing a framework for knowledge extraction. (The content marketing folks will appreciate this as well.) Set up knowledge-preservation practices from the beginning: focus on transparency, skills-based access, communication tools, metadata, and the use of templates. These practices will prepare the ground for the content engineering of systems that steward the discovery, nurturing, and sharing of quality content.