DocOps Discussion: Process documentation and their target audience #460
Replies: 6 comments 1 reply
-
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. |
Beta Was this translation helpful? Give feedback.
-
A few off the top of my head:
I've tried to generalize these as much as possible, as opposed to getting granular on roles. |
Beta Was this translation helpful? Give feedback.
-
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 evergreen1 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 model2, 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
|
Beta Was this translation helpful? Give feedback.
-
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" |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
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":
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:
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. |
Beta Was this translation helpful? Give feedback.
-
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:
Examples of process artifacts include:
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.
Beta Was this translation helpful? Give feedback.
All reactions