Ultimately, Docs determine the developer experience.

In our interactions with customers we have seen that most of them don’t have tech writers. That’s why we have been doing research about how to help them to set up the processes to make their own documentation, and part of that is our research about editorial review processes.

If your objective is to transform your business, and to make APIs an integral part of how your organization works, then you need to distribute API ownership throughout your organization. A central API team is great to prove the business value of APIs, but if you build APIs as a one-off project instead of a continuously developed product, your APIs will soon fall into disrepair.

That is why we think central API teams should transition from an “API pilot team modus” to an expertise center that supports developers throughout the organization. Sharing scarce skill sets like API documentation expertise and developer experience best practices. We think this is the best way to transition an organization into the API-first mindset, necessary to capture the value of internal agility.

Organized by the Center for Information–Development Management, IDEAS is a two-day industry conference. The theme of this summer's conference was Judicious Editing, where we spoke about centralizing the editorial processes and distributing API ownership throughout the whole organization.

The following is an abridged transcript of this presentation, which goes in layers.



I will first talk about systems and about culture. Then about API documentation, and at the core of the focus is the idea of fitting documentation practices into the software engineers' workflow. Then we will circle back to the gamification of API documentation, and finally I will talk about how you can combine systems thinking and open source software culture.

Culture. Systems thinking. There is no cookie cutter.

Editorial services don’t happen in a vacuum, they need to be adjusted to your company culture. Companies are not machines where you can drop a new piece in and it will just work: you need to look at the whole system and the culture that informs its behavior.

We think there are patterns applicable to documentation scaling, and at the end of the presentation I will return to the idea of patterns and show you an innersourcing pattern template. The aim of this presentation is to give you a scaffold for your own learning, and your own research into centralizing your documentation efforts.

Flock behavior is not a sum of individuals

Take this flock of starling birds: they become something different because of their interactions. It is not the simple sum of birds and there is no central orchestrator. Companies are similar – or at least there is a cultural shift happening to urge companies, even very large enterprise companies to move like these murmurations of starlings.

Open source culture has transformed the software industry – because by now there is no developer who hasn't somehow been in touch with the tools that the Open Source communities created. Be that GitHub or StackOverflow, where Open Source conversations are happening, these tools were built to enable Open Source – and now in turn they are influencing closed source software development. Although for complicated market share reasons, companies with a reputation of being relentlessly closed have by now accepted that the game is afoot.

Open Source is Agile: it is not a centrally planned but a distributed effort. Companies are trying to integrate this into their internal software development culture. The InnerSource Commons was explicitly started to help enterprise companies with this transformation. One of the key tools in this community are pattern languages.

Humans are special, because we can show a larger range of interaction patterns and we can switch between these behaviors. But given a certain organization, and their already existing interactions, there are certain behavior patterns that are easier to implement than others.

How can you change the behavior of a system? You want to make it more like the collective behavior that the existing open source communities show. This is exactly what the InnerSource community is trying to map out.

Pattern languages

Patterns are a way of describing a repeatable, proven solution to a problem with a context. They follow a simple form that helps people wanting to implement the solution to understand the constraints on the problem, the forces that must be balanced and the resulting situation you are left with once the solution is applied.

What is crucial to understand is that these working patterns cannot readily be applied to any situation: they have their pre-conditions and their context to consider.

Systems thinking is going beyond linear thinking

To be able to adopt these patterns, one must think in systems. Ecosystems if you like.

In linear thinking the same cause will always have the same effect. Systems thinking is going beyond that. You have to look at corporations as complex systems with a purpose and with many interactions among their parts. Systems thinking further shows that you can replace individual parts but the same system keeps running. To really change a system, you have to work on its interactions and on its purpose.

When you want to start providing centralized editorial services, the existing processes and company culture will impact how you can introduce these services.

Docs appreciation

For example: an organization with lots of technical writers starts downsizing. They introduce an automated editorial system to replace existing technical writers. This won't work, because you cannot at the same time give a signal that docs are not valuable, and yet expect developers to start doing documentation.

Instead you could set up automated editorial services as an additional unifying force to standardize the editorial practices across business units.

Supporting infrastructure

On the other hand take Organization B, that doesn't yet have a well worked out documentation practice. They could introduce a centralized editorial service as a tool that supports developers when writing documentation, as a first step towards a better documentation infrastructure. The key is to nudge and enable the documentarians and the software engineers to iterate the setup together.

We ourselves are also still exploring this and we by no means have a comprehensive solution to your docs scaling problems. But we think cultural context is crucial.

What is a developer portal? What is DX? What is a developer journey?

An API developer portal is the interface between a set of APIs and their various stakeholders. It is where you publish your API's documentation but it is more. The portal can play several roles to achieve the business goals of an organization. It's more than reference docs. You will also need onboarding materials like tutorials and guides. Sandboxes are great for evaluation.

A developer portal is a self-service hub for your API, you have to provide your users all the documentation so they can find all the information themselves. You can use your developer portal to give your users the means to communicate with each other.

Release notes, legal documentation, status pages are your entry level in reliability. Use cases, worked examples are helpful in the evaluation phase as well. SDKs are great help for your beginner level user, and on the long run they help you test and standardize across your APIs.

At Pronovix, we have done extensive research into how API developer portals are used, what elements are necessary and how to setup the information architecture to serve your users' needs best.

What is Developer experience?

It is all about motivating and engaging your developers, and giving them the right tools to achieve their goals.

You need both intrinsic motivation and extrinsic motivation: for the site to be successful, people need to enjoy the work simply because of the work itself and the actions it provokes; and they need to get rewarded for work done. When you are able to get people enthusiastic along their journey, and you don’t constrain them, they might even recommend your API to others.

Developer experience is also about achieving things and about not experiencing friction, like obstacles when they one uses the developer portal. Friction can occur at every stage of the user journey. The easiest example is probably that when there’s no documentation that would answer the questions you have at that specific moment: that causes friction. A site with great developer experience means that users like to use that site, that it matches their expectations, that they feel “the site” pays attention to them, their needs and their goals.

User journey

All the stakeholders have their own user journey, which means they all have different expectations during the time they use the portal: people will take different actions to achieve a goal. These actions are the user journey stages.

To be able to address those individual developer needs, it is best to address the developer journey stages.

A central content team can be the composer of streamlined user journeys

A central content team can be the composer and the supporter of these user journeys. In case of API documentation, one has to look at the whole docs lifecycle and cannot entirely separate editing from writing. The type of developer portal also plays a role. One of the strongest driving forces behind API programs in large multinational companies is to increase their internal agility. Most successful public APIs started out as private, internal APIs.

Internal API portals

Public-facing API projects, which can be considered products, can afford to invest a lot more money in documentation and user experience driven developer portal improvements. Internal APIs rarely have that luxury.

However, only a few companies have many product APIs. Usually there are a few external APIs; and then there are a lot of internal APIs , those are what connect everything together within the organization.

Pain points of internal APIs

There are numerous problems with the execution of internal API programs, they are the kind of frustrations that make people change their jobs. How do these problems evolve?

A lot of teams are making one-off internal APIs, because often a very particular API is necessary to do a specific integration. Realistically, the first team to use the integration may be the only one for a while, and so often the team creating the API just sets up the integration with the other department and they do not document the process, well or at all.

This results in very poor discoverability, confusion in domain language across departments and the lack of API design standards keeps it all inconsistent.

The API's description is often bad, written only from the creator’s point of view, and it may be only six words. You are already lucky if you get the API's reference docs. No tutorials, no conceptual docs. Maybe a bad, short description that is part of the Open API specification, because a short description is a compulsory field for submission.

Onboarding is often only happening in live workshops. This in turn allows a fragmented and complex authentication process to linger on.

Map and formalize the upstream developer journey

How can a centralized editorial utility address these issues with internal APIs? You have to model the developer journey, identify its stages and standardize at all stages possible.

Upstream developer journey

At Pronovix we developed an upstream developer journey model that helps us to think about how to improve the experience of the developers who build the API. This is especially important for internal-use APIs because you will not have the budget to iterate on docs to polish them after publication. Traditionally, it would be at QA and publication where an editor comes in, but a central editorial team can look at all the steps to reduce the need for interventions.

For example:

  • If you can step in at the enterprise-level inventory as editors to make sure the names and short descriptions make sense outside the departments, you can reduce discoverability problems and duplication of work.
  • If you can get your engineers to agree on style-guides for API design, the result will be more consistent APIs that in turn allow for docs re-use.
  • You can adjust the submission process to the developers' tools and toolchains.
  • Templates and guidelines for tutorials and conceptual docs can get you at least a first draft.
  • Quality assurance and publication is the field for implementing docs as code practices and extensive automated testing.

All this will have a positive effect on your feedback and support options, and you can further push the envelope with gamification elements.

What can tech writers do to streamline an enterprise company's API documentation?

Your company is probably already thinking about this. Technical writing practices are rapidly changing, and the pattern of tech writers basically becoming technical information editors and documentation community managers is coming your way.

How can a technical documentation editorial process interface with the software code? Let's look deeper into what is docs as code and what you have to consider.

Docs as Code

The interface is basically when make a pull request. If you manage documentation in the code repository, then the editorial process becomes just like a code review. This has a psychological and a technical ripple effect.

[The following explanations and examples on the Docs as Code approach are paraphrased from writings/presentations of Margaret Eker, Anne Gentle, Riona Macnamara, Jennifer Rondeau, Emma Jane Hogbin Westby, Tom Johnson, Steve Szabó.]

As long as it is only writers creating documentation, the traditional help authoring tools are just fine, they were designed for single sourcing, dealing with ontologies and generally for docs heavy-lifting. They come however with per-seat licenses and are far away from the developer engineering toolchains. Especially in case of API documentation, such is not a maintainable approach any more.

The documentation process needs to be integrated into the engineering culture: into the codebase and into the existing engineering workflow.

Instead of authoring, managing and publishing documentation separately (maybe in multiple formats) using writers' tools, in a docs-like-code culture developers can add documentation to their code in their own tools following their own logic and habits such as their flavor of version control and code reviews. This brings a radically simplified authoring, editing and publishing workflow.

The codebase and its documentation can be in the same git repository: if one can find the code, one can also find the documentation; then consume it either in the source or rendered in a browser.

This paves the road to documentation being part of the Continuous Integration and Deployment processes and being part of your definition of done. Especially in case of APIs keeping docs and code in lock-step is crucial.

Ultimately, Docs as code is

  • web delivery
  • continuous integration
  • collaboration for documentation using code systems and
  • content management using those same code systems

In practice you will be:

  • Employing the principles of version control
  • on docs living with or near code
  • you will be using plain text markup languages (md, rST, AsciiDoc),
  • you will run validation checks (links, terms, style, format),
  • and you will hopefully integrate your docs into your CI/CD processes.

To illustrate, this is a simple git workflow for documenting.

  1. You would create a new branch for the draft.
  2. When the doc is considered done, you make a pull request.
  3. Then you assign a doc review.
  4. You will update the doc with the necessary changes then merge back the final document to the master branch. You are ready to publish.

Riona Macnamara's adviceon how to implement such a huge change in your organization:

  • Focus on the engineer, adapt to their existing tools, avoid context switches.
  • Start small and be reliable, iterate often.
  • Impact the life of the users, solve their problems within their workflow.

Version control is teamsport. Embracing the software coding toolset and culture for documentation is not an easy shift from a legacy situation.

A straightforward case would be if:

  • all your docs and code are open source,
  • you have to solve a small team's internal processes,
  • you have a single repository,
  • and you need one website output.

You will have a complex setup if you have to operate with:

  • a closed source
  • and you need to publish on both web and print,
  • if you have to integrate with applications or a large website,
  • if you have a Windows System,
  • if you are working with large teams and/or people outside your organization,
  • or if you have multiple source repositories.

There are, however, gotchas to this. Anne Gentle in her talk as Developer Experience Engineer for Cisco DevNet pointed out some hard questions:

  • Tech writers who used to be responsible for all deliverables now have to rely on other teams for integration work.
  • Managers of higher-paid developers will want to make docs the problem of the lower-paid writers.
  • Getting resources for web development that is unrelated to product development is a problem.
  • Who gets to control what gets done when? The Dev team or the Docs team? Product or Support? You need a Content strategy overall across disparate sources.
  • Style guides, image standards, tool standards, basically, agreement is necessary.

Docs development environment

Margaret Eker and Jennifer Rondeau gave a fantastic talk about how to reconcile docs and code: how to implement a truly iterative documentation process into the code workflow. Their advice:

In a docs as code workflow, updates and small changes to your documentation are almost instantaneous. However, to document new features or an even entirely new product, you have to adjust the scope. In the planning phase you have to account for the documentation types you need and you have to have a content model for each type that defines the parts, structure and organization for reference, concept, task or other types.

In the development phase, you are going to write, review and test content, just like you would do with software code – and you need a documentation development environment set up. You do need those content models and templates and you will also need to provide information on how to contribute: create guidelines and training materials.

In the research phase you will have to map the user stories into docs and see how these get implemented into product features by the developers. The time needs to be planned and the documentation has to go hand-in-hand with development: this way, coders can provide at least the first draft of the docs.

If you have a CI/CD environment set up, you can commit your first pass at the docs into the repo and immediately see the rendered content in a staging environment.

Even with clear principles and best practices to follow, we find there is a need for editorial guidance and review. The technical writer's traditional function changes to that of a project manager for documentation, but writing well is still a learnt skill and editing is still partly a soft skill.

There are some gaps between how we can treat code and docs: code is extensively and automatically tested. Docs used to be tested mostly manually, mostly on language and syntax, as part of the review process. The code frameworks, however, can be leveraged to do testing of docs. Separate the traditional full review process into:

  • automatable parts, such as linters for syntax and language and examples testing;
  • and into the only human-doable reviews, that are user stories and product implementation standards.

Docs in Definition of Done?

Is it possible to not allow a feature merge until the docs are done? Rob Woodgate has an exhaustive poston what to consider:

  • Is documentation part of your deliverables? YES if it's an API.
  • Can other team members write the docs? YES if it's minimal docs for an API.

The rest you need to carefully answer for yourself:

  • What proportion of the docs can be done quickly or be automated?
  • Do you get all the information in time to work with?
  • Do you have standards and templates?
  • Do enhancements happen at the beginning of the sprint, and bug-fixes at the end?

In an optimal model the developer engineer drafts the complex feature's documentation. The technical writer team ensures compliance with the style guide and the format constraints. Technical review becomes a priority.

Adopting the engineering workflow and tools gives a much higher chance to put docs into the definition of done.

What can't be automated? Empathy.

A little about the element of human empathy and about semantics.

"It would simplify our work greatly to automate the specification and concentrate our talents in developing tutorials. This decision may look obvious in hindsight, but we had to do some research before we came to that conclusion." Tony Sansone, MongoDB

To date, an API's conceptual documentation cannot be automated, but we can do a lot to make it machine consumable. We need to establish API description formats as a middle ground, to write concepts alongside code and enable developers and tech writers to collaborate according to docs like code practices.

Documentation as a thinking tool

My first meet with the warmly welcoming technical writer folks at the Write The Docs community was in 2015 in Prague, where Zdenek Nemec, API design consultant, also co-creator of the API Blueprint standard talked about writing about what really matters.

In his presentation, "Writing for thinking", Z said the following: "Documentations of today are designed to sort of funnel the users into your systems, to get something sold or to get signups. We are at an age where people are programming first before they start thinking. I propose that we should shift our minds and think of Documentation as a thinking tool, it helps people to think about how a system works. Documentation is not just a marketing tool." "The very important parts in API documentation are obfuscated and burdened under technical details. You know how to use it but you don't know what it is."

We can give all the technical details of a system, we can automate their description, but there is a human element of empathy within the reader's specific context that is necessary to explain them what something really is. As Z said, we need to think about what is it we are documenting, and what makes this something unique. In case of APIs, it is the data that matters. Tutorials are nice, but they are already narrowing down your thinking.

Define domain semantics first

First explain the specific terms in your business, that is your domain semantics: say what is the data exposed by the API, together with what you can do with that data and how.

You need to get the software developers, the business stakeholders and the technical writers to decide and define the domain semantics first. This results in systems that can last longer, that can evolve and scale better.

Ontology, domain knowledge

Controlled vocabularies can bring back the lost glue into your fragmented documentation. Emilie Boillat gave a talk about how you can start small with a glossary or a thesaurus and then evolve it into a taxonomy or better yet, a full-out ontology. Ultimately, controlled vocabularies and such clear semantics are what can enable machines to consume APIs, because until then it requires humans as the ultimate semantics machines to connect the unsaid dots. So you would want to bring in a data modeling expertise, to set up the ontology just right for computing systems to understand.

Ontology engineering aims to make explicit the knowledge contained in software applications, and organizational procedures for a particular domain.

Since domain ontologies are written by different people, they represent concepts in very specific and unique ways, and are often incompatible within the same project. As systems that rely on domain ontologies expand, they often need to merge domain ontologies by hand-tuning each entity. At present, merging ontologies that are not developed from a common upper ontology cannot be automated, is a largely manual process, it's time-consuming and it's expensive.

Linters

Linters on the other hand, are already here to help you automate docs review and build tests. Linters are testing tools to improve software code. They flag mistakes, recommend alternatives, remind you of missing elements or outright stop you if so set them. Originally, you could lint for syntax only, but by now you can also check semantics and style. Linters are meant to be part of your automated technical toolchain, in your editor and your build system.

The principles of linters are available for creative writing, mostly for the English language. In technical documentation, you can mix code linting and language linting together and the options are getting more and more elaborate and sophisticated.

A linter assisting your reviews and your editorial team, in your automated or semi-automated docs build is a great step towards consistent, complete and correct API documentation. Making contributions easy is the goal.

remark + retext

Lyzi Diamond from Mapbox gave a toolchain introduction on how they go from markdown to linted and auto-built, nicely rendered API docs. They use docbox, that is Mapbox's version of the open source remark, which is a markdown parser that builds a syntax tree from markdown files. Then they use the mapbox standard of retext which is an open source ecosystem of plugins, to enforce linguistic correctness and consistency.

The decisions on what to do with the linter's warning messages is complicated. Avoiding false-positives is crucial for company-wide adoption, for instance. The settings are a balancing act between too precise or not precise enough. You will probably iterate a lot on which doctests must pass for build.

atom-linter-ibmstyleguide

If you enforce the reference docs in a certain format, and they need to adhere to the overall standards, that will help to improve the quality of the deliverables that get published in the downstream developer journey. It is usually a challenge though, to make all your people go through the standards that you established. Arnaud Lauret has a site on API styleguides. There are tools that can automatically check your docs against a style guide.

For example the IBM Style guide linter was made by the Write The Docs community. You can also find testing tools from the Plone community.

Gamification

Humans...

You can have a workflow process where you can move to next step in the workflow by adhering to certain criteria. The key could be gamification. Basically, you would do experience design: you create a process where you have quality checks and an experience where one is motivated to go through that process.

Experience design:

So what is gamification? It’s not play, it’s using human triggers to increase engagement, by applying the elements of game design.

For example, in a large enterprise company you can have internal dashboards for showing how many APIs you have, the development status and quality of those APIs. You can have an overview of the APIs with 5-star ratings depending on what criteria they have passed. This is on the dark side of motivation.

In UX design, we create engagement flows with engagement loops. If you have a community around your APIs, it is a good idea to spotlight the latest contributions, to enable immediate interactions with the documentation, to let users follow up on the state of your API.

You can go beyond dashboards and dig deeper into human psychology.

The Octalysis model was developed by You-kai Chou. It's a design framework, that lays out the structure for analyzing the driving forces behind human motivation and engagement. You would use it to apply the eight core human behaviour drives, to motivate a user to complete a task more efficiently through an interactive experience.

There are many other models. Octalysis is an analytical, measurement framework, applied by enterprise companies such as Ericsson, Cisco, Accenture, Lego, eBay and many more.

The eight Core Drives are charted on an Octagon shape not simply for aesthetic purposes, but because the placement determines the nature of the motivation: the basic balancing forces behind our actions.

The left side of the octagon gathers extrinsic motivational drives, while the right side are of an intrinsic nature. Those on top are the white hat motivators, those that leave us feel good but do not create urgency - the flip side is the black hat motivators, those actions we keep taking although they leave us feel bad.

In experience design, we would first set the key behaviors we want to see from our users. Then we analyze what sort of interactions happen among the users. We then pick the gamification elements that fit this behavior. Applying the octalysis at this stage would show us what type of system we have and help shifting it in other directions.

Take another look

You may know or even practice some or all of what we talked about so far:

  • designing developer journeys,
  • treating docs as if it was code,
  • about the definition of done,
  • the automation of your docs testing,
  • gamification.

I invite you to now take a mental step away from their daily practical details and look at them differently.

What we should see are patterns.

Innersourcing

There are patterns that are proven to work to help innersourcing and the cultural change that the practice of innersourcing requires. Innersourcing is the adoption of open source development paradigm in organizations.

Developers are always keen on patterns that they can reuse. The InnerSource Commons is a community around this, they hold events and conferences about their results.

We need to find a way to break down the barriers and nudge people to collaborate.

Adopting inner sourcing practices can help you with

  • software reuse across teams
  • improving the quality through more reviewers with more eyes
  • opening up innovation to a shared, broad expertise across your whole organization
  • potentially faster time to market
  • standardization and better inter-department mobility of developers.

It is key to understand that innersourcing is not a defined methodology but more of a psychology and adoption of those behavior practices that fit your company.

InnerSource Pattern Template

There are great research efforts going into capturing and analyzing these patterns of innersourcing.

Hewlett-Packard, Alcatel, Phillips Healthcare, IBM, SAP and BASF are in the vanguard of these efforts, you can find several intriguing case studies from them.

Every company has its own development culture and practices. There are no cookbooks for InnerSourcing yet. Open-source projects usually rely on a product to drive the circle of develop/publish/use, test/contribute. The InnerSource Commons uses patterns to serve the same purpose: these patterns provide a level of abstraction showing a proven solution to a specific problem within a given context.

We think that innersourcing patterns are applicable to documentation and we are now working on a patterns library for API documentation.

"We have found that top-down doesn't work but bottom-up doesn't scale." Riona Macnamara

An innersource project is not owned by a team or a department. You can contribute or use others' contributions wherever you are in the organization. For the same reason, it can be a challenge to start, and to evaluate your progress.

Patterns can help to change an organization’s culture and behavior, to make sure departments use the same standards and to nudge people to do something the same way without forcing them.

Distribute API ownership throughout your organization.

Most organizations never consciously address the experience of the developers that create APIs, the upstream. This is only logical, upstream Developer eXperience doesn’t always need attention: a team that is dedicated to APIs will overcome friction on its own terms. In large enterprise organizations, however, where API development might be a secondary priority of a team, upstream DX can make the difference between a failed and a successful digital transformation initiative. If your objective is to transform your business, and to make APIs an integral part of how your organization works, then you need to distribute API ownership throughout your organization. A central API team is great to prove the business value of APIs, but if you build APIs as a one-off project instead of a continuously developed product, your APIs will soon fall into disrepair.

That is why we think central API teams should transition from an “API pilot team modus” to an expertise center that supports developers throughout the organization. Sharing scarce skill sets like API documentation expertise and developer experience best practices. We think this is the best way to transition an organization into the API-first mindset, necessary to capture the value of internal agility.

This presentation credits the generous work of many people.

The scope of this presentation didn't allow for the many practical real life toolchain examples and war stories that you definitely want to hear when you are on a digital transformation path yourself. Although there is no one toolchain that fits them all, we heartily recommend listening to what other teams went through to streamline their docs creation and maintenance. We host a collection of such presentations from smart and generous people from around the globe. The API the Docs and the Write the Docs communities have video archives too.

We would love to hear your own documentation scaling story.

About the author

Laura Vass

co-Founder. Financial Manager. Technical Writer, Editor.

Co-founded Pronovix in 2005.

In daily operations Laura is cheerleader and copy editor of the Pronovix writer team. Since we specialized our company in developer portals, almost 3 years ago, our tech writer team of five has been researching, and reporting on events (some of which we co-organised) in the API, DevRel and documentation space. We publish video recordings and text recaps of these events, and write our own findings in blogposts aimed at a wider (not only technical writing) audience.

Pronovix is a very active member of the Drupal and the Write The Docs community. Laura is co-organizer of the Amsterdam and the Brussels Write the Docs meetup groups and of the API the Docs conference series.

Proud contributing writer of the Drupal 8 end user documentation.

She is also a zentangles-evangelist and avid yarn-collector, eliminating imaginary bottlenecks to creative freedom.