DocOps Discussion: Process documentation and their target audience

[ADubhlaoich]

Overview

Hello! This is the first of many DocOps Discussions: an opportunity for DocOps and interested parties to share perspectives on how DocOps approaches a topic.

The DocOps team works collaboratively within itself, as well as with product teams across the organisation. Much of the work we undertake has far-reaching impact, and many things related to work are discussed asynchronously.

As a commitment to working in open source, we have decided to shift some of these discussions into public, as our mental model of "stakeholders" include people outside of the organisation, and colleagues that may not ordinarily be part of design brainstorming.

Please familiarise yourself with the NGINX Code of Conduct when engaging in discussion. Assume best intent, and ask clarifying questions if someone states something you do not understand.

This discussion will close at 3PM IST (Irish Standard Time) on Friday, May 2nd.

Process documentation and their target audience

To establish a contextual dictionary:

• A process is a task someone engages in
• A process artifact is an output from or related to a process

Examples of process artifacts include:

• README-style documentation
• Issue templates
• Scripts for specific tasks

As of the start of this year, the documentation repository is now open source.

Prior to this, many process artifacts such as the README documentation and Makefile were maintained and replicated across other open source products where product code and documentation were colocated, such as NGINX Agent, NGINX Gateway Fabric and NGINX Ingress Controller.

All product documentation being consolidated into this singular repository it allows it to become a single source of truth.

When writing product documentation, we establish personas as part of formal content planning.

This level of detail has not been applied to our process documentation until this point.

The possible personas for our process documentation encapsulate everyone, since it's now open source.

To clarify the focus of the process documentation, we would like to establish a persona: this will help DocOps determines what gaps might exist in our process documentation and what level of detail should be included.

[ADubhlaoich]

As the poster of the discussion, I will refrain from adding my perspective until tomorrow so as to reduce any bias in the subsequent responses.

If you're reading this message, you are someone who might possibly use this process documentation.

Any perspective is invaluable, such as what you would like to see more of, or anything that may have stopped you from contributing.

[jputrino]

A few off the top of my head:

• People who have a high degree of familiarity with open source development and tooling (e.g., git, GitHub, command line utilities in general).
• People who have little experience with open source development and tooling.
• People who have a high degree of subject matter expertise wrt NGINX.
• People who have technical writing expertise may have little or no direct experience with NGINX.

I've tried to generalize these as much as possible, as opposed to getting granular on roles.

[ADubhlaoich]

Generalising the users is a big part of why I'm starting to explore job stories instead of always defaulting to user stories: focusing on process story over user identity.

Outside of discrete planning there's certain implicit personas for our product documentation given the nature of server tooling and infrastructure: as a result of this, we have an idea that there's a baseline level of technical knowledge someone would come into them with.

I'm inclined to treat our process documentation the same: I will elaborate in my own reply.

[ADubhlaoich]

There were two drivers for me to start this conversation: the lack of clarity for intended audience discovered in the pull request "feat: Update Contributing guidelines for writers" and an issue I have to update the README to reflect the state of the repository.

I think this lack of clarity has also kept "Update CLOSED_CONTRIBUTIONS.md to clarify internal contribution process" open, but that could easily be the fact that Mike & I are the most vigilant about PRs unrelated to our product assignments, and thus nobody else has seen it.

Prior to open sourcing the documentation repository, the most prominent NGINX projects for open source engagement have been NGINX Ingress Controller and NGINX Gateway Fabric. Through working with them, I don't meaningfully delineate between an "internal" or "external" contributor or an "engineer" or "writer" when it comes to managing work.

Depending on the team, the primary author of a given document could be a technical writer, product engineer or manager (Of some description). I strongly believe we should assume a certain level of technical knowledge as our default baseline.

I have approached managing our process documentation the same way I have our product documentation: using plain language as much as possible, respecting the reader's time, and assuming they have enough context to understand the factors involved.

Documenting the factors they don't have context for ends up being the meat of instructional information. In general, we don't redocument third party tools, and we haven't written tutorials to explain things to people.

I do think there are cases where we will need to document for specific use cases outside of an evergreen¹ context.

Nobody but F5 employees will ever have access to nor need to use our internal mirror of documentation for closed contributions: it wouldn't make sense to have that instruction in front of every possible contributor. It's just noise, even to the engineering teams that would never need to use it.

Similarly, some specific instruction for people with less technical knowledge could attract more open source contributors, but if someone is interested in working in open source, they will need to familiarise themselves with the common tooling of the ecosystem no matter where they begin.

I do not believe we should be simplifying for them at the expense of our existing contributors. I think this is great intention but misplaced execution: if there's confusion about how to contribute, fixing it will benefit everyone. We should not ignore the fact that outside of the writers, engineers are the most common authors, and the actual experts on how a given use case works.

In the swing dance community, some scenes have designated "dance ambassadors" or "dance angels". Their purpose is specifically to go dance with new people on a given night, whether they're new to the activity or to the local scene (Such as visitors).

From anecdata, a lot of people who were engaged by these "advocates" were initially happy to be asked to dance, but usually felt somewhat betrayed once they realised it. It made them second guess why they were friendly at all, and patronised to an extent.

Although we want more open source contributors, we will probably always have a stadium model², and I want to reinforce what it means to work in open source for our own consistency and appeal to future contributors. The extreme end of prioritising contributors for the sake of contributors is getting bombarded with noisy PRs as Hacktoberfest tends to create (Less so since you don't get t-shirts anymore).

Quality over quantity, always.

_{(I also think our process documentation has IA problems, but that's planning work following this discussion).}

Footnotes

1. Evergreen is a term used to denote something that rarely changes state despite external circumstances, derived from trees. A documentary is evergreen since it's scoped to a specific time period, whereas a news report is concerned with recent events. ↩

2. The stadium model refers to the ratio of contributors and users. Stadiums have low contributor growth and high user growth. See page 53 of "The Making and Maintenance of Open Source Software" by Nadia Eghbal. ↩

[JTorreG]

I think Alan has expressed my own opinions here much better than I would ever be able to do myself.

100% agreed on "not simplifying at the expense of existing contributors"

[nginx-jack]

I agree with Alan on this point. In my opinion, if someone falls into the (presumably small) category of non-technical contributors who still wish to be involved, there remains the option of opening an issue or starting a discussion. Someone with the technical skills can then choose to take on the work, provided we figure it's worthwhile.

[jputrino]

To take the less popular stance and ensure that we are taking an egalitarian approach to supporting all potential contributors...

I agree that we don't want to cater to one group to the extent that it becomes detrimental to the experience of another. We do want to create an open and welcoming community focused on the NGINX documentation. We should make sure our barrier to entry isn't so high as to prevent people from participating when they would otherwise genuinely like to do so.

From Rule 6 of "Ten simple rules for helping newcomers become contributors to open projects":

A core concept in the theory of communities of practice is that of legitimate peripheral participation (LPP) [2, 3]. Newcomers become members of a community by participating in simple, low-risk tasks that further the goals of the community.

In a project focused on code, documentation is generally one of the peripheral tasks via which new community members can get their feet wet in a low-risk way. For a project focused on docs, things like translation might fit into this category, as would having low-risk tasks that center on general writing needs and don't require specific technical expertise.

From Rule 7:

One way to facilitate LPP is to make it easy for newcomers to get set up so that they can start work on contributions. Getting set up to work on a project—going from "I want to help" to "I’m able to help" to "I’m helping"—is often someone’s first experience as a community participant. Any complexity or confusion at this point is therefore a significant barrier to participation [39].

I'm not arguing here that we want to skew all of our process docs heavily in the direction of the newcomer. In general, in our docs we try to focus on the "80% use case" and it makes sense to do the same here. That could mean we have onboarding resources in a Discussion thread or wiki post; as long as it's a visible resource that we can point people to if they ask for help (or, better yet, they can discover so they don't have to ask for help), I'll be happy.