Take a structured approach to improving opctl documentation

[gunnarg-remitly]

💥 Proposal

Establish a direction to take opctl documentation.

I believe the opctl project has the desire and ambition to improve its documentation. Better docs will help users figure out how to use the tool, will help non-users understand how opctl can help them, and will help power users/contributors level up their game.

Here are some things I believe could help improve the documentation

Audience-focused Documentation

Each identified audience should have a type of documentation aimed at their specific needs. The existing documents target devs without prior experience (Setup, Training, Homepage) and experienced users/maintainers (Reference, github.com/opctl/opctl). That leaves developers with prior experience and managers facing a gap in documentation. Developers with prior experience would be well served with a manual or cookbook style document. Managers would be well served with a combination of a feature list and comparisons of opctl to other approaches that manage the same problem. Managers are also served by the homepage giving an elevator pitch about what opctl is.

Developers without prior experience wanting to try opctl

This audience is developers that are experienced in computing (eg coding, operations, CI/CD, etc.) that have some experience with Docker and want to try opctl to streamline their docker process. This group wants to understand how to install opctl, how to set up a basic op, and how to run their new op.

Developers with prior experience wanting to determine how to do a specific thing with opctl

This audience is people that use opctl, but are not advanced users. They probably inherited a project using opctl and mostly copy-paste from other working ops to achieve their goals. This group of people may not know exactly what opctl concept they are looking for. Instead, they have a particular goal in mind and want to match that goal to a particular opctl feature. They need to streamline their docker process with opctl, and so need the syntax explained, and concrete examples to play with.

Experienced users/maintainers wanting to look up a property of opctl

This audience is people with deep understanding of the innards of opctl. The group of people want a quick way to navigate to the definitions and low level technical documentation of opctl concepts.

Managers of teams that want to try opctl

This audience does not directly interact with the tooling, but wants to evaluate tools for use with their team. They have a specific set of business goals they want to achieve and want to evaluate the ability of tools to provide leverage to meet those goals. Often this is in the form of a checklist of features.

Note: this isn’t necessarily just managers, but is supposed to be a useful visualization of who to write for.

Proposal to re-arrange documentation

• Retain the existing Setup, Training and Reference documentation.
• Revisit the hierarchical tree structure of navigation and consider a “library” metaphor where each document is a standalone section of the website.
  • Encourage dense interlinking between the different documents within the opctl “library”.
• Create a new “Opctl Manual” that bridges the gap between the tutorials in training and the reference.
  • Alternatively, refactor the “Training” documentation to be a manual with a tutorial cookbook.
• Create a training repository with pre-created training ops that can be referenced from training documentation
• Add examples to the Reference documentation so that the syntax is clearly highlighted and the usage of the opctl concepts is illustrated.
• Tune up the homepage to explain in somewhat more detail how opctl will make development and operations easier.
• Include a hello world example in the introduction

Adopt either a policy, or a vision document

I think this policy should exist as a document within the opctl project to define how the opctl project thinks of documentation. I don’t think it should be the end of discussion about documentation, but rather the starting point to create plans and or visions for what to do with the documentation. If folks feel the policy is too prescriptive, off-putting or just not needed with a project as small as opctl, I'd advocate for writing a vision statement for where opctl documentation is going

1. Each top level documentation type shall define the audience(s) that it addresses.
2. Top level documentation types are written to fulfill the needs of the audience(s) they address.
3. Each individual document shall have an educational goal. An educational goal is of the following form: “Given a reader with knowledge, skills and abilities a, b, c after reading the document the reader will have knowledge x and/or skill y and/or ability c.”
4. Documents of similar types shall have similar forms. Similar forms means they shall have similar section headings, ordering of section headings and style of content.
5. Document style shall be chosen with respect to the needs of the audience it serves.

[gunnarg-remitly]

Rephrasing the policy as a vision:

Opctl should have documentation that makes it easy for beginners to pick it up up, and experienced devs to quickly answer questions. To serve this end, an audience-focused approach should be used. Each audience should have a type of documentation that addresses their specific and unique needs. The documentation should be written with the goal of teaching in mind, so that after reading a doc, and trying out an example, the reader has gained one or more skill(s). Documents that serve similar audiences should look similar so as to not surprise anyone.

[chrisdostert]

@gunnarg-remitly How do you see this applying to material that serves multiple audiences? The one I have in mind is reference docs. For sure advanced users will be using it to look stuff up quickly and get out, but I'd expect beginners to likely need to use it for similar purposes.

[chrisdostert]

@gunnarg-remitly How do you see this applying to material that serves multiple audiences? The one I have in mind is reference docs. For sure advanced users will be using it to look stuff up quickly and get out, but I'd expect beginners to likely need to use it for similar purposes.

I guess that's covered by your use of the term "audience(s)" as opposed to just "audience"

[gunnarg-remitly]

The way I think of that is that a given documentation type has a primary audience. It may have secondary, or even tertiary audiences, but when reviewing the writing you should think "audience a, exemplified by fake person alpha will receive it this way, whereas audience b, exemplified by fake person beta will likely receive it that way"

Plus, I'd say diskspace is cheap, linking is easy and there isn't any real cost apart from the initial time of writing, and subsequent time of updating to have the same information presented in multiple forms (a trick is recognizing, or tracking when/where the same information is presented). It's a type of teaching, and taking different approaches tailored to the individual student is going to help get those students up and running.

[psamaan]

Please thumbsup/down the following Documentation Policy Proposal:

1. Documents have two high level types: Reference Docs and Training Docs. All Training docs must follow the below guidance. All Training Docs must also link to Reference Docs.
2. Each document shall define the audience(s) that it addresses.
3. Documents are written to fulfill the needs of the audience(s) they address.
4. Each individual document shall have an educational goal. An educational goal is of the following form: “Given a reader with knowledge, skills and abilities a, b, c after reading the document the reader will have knowledge x and/or skill y and/or ability c.”
5. Documents of similar types shall have similar forms. Similar forms means they shall have similar section headings, ordering of section headings and style of content.
6. Document style shall serve the needs of the audience it targets.

[psamaan]

Please thumbsup/down the following Proposal to re-arrange documentation:

• Retain the existing Setup, Training and Reference documentation.
• Revisit the hierarchical tree structure of navigation and consider a “library” metaphor where each document is a standalone section of the website.
  • Encourage dense interlinking between the different documents within the opctl “library”.
• Create a new “Opctl Manual” that bridges the gap between the tutorials in training and the reference.
  • Alternatively, refactor the “Training” documentation to be a manual with a tutorial cookbook.
• Create a training repository with pre-created training ops that can be referenced from training documentation
• Add examples to the Reference documentation so that the syntax is clearly highlighted and the usage of the opctl concepts is illustrated.
• Tune up the homepage to explain in somewhat more detail how opctl will make development and operations easier.
• Include a hello world example in the introduction

You can also comment with specific line item change suggestions or concerns.

Trying to drive for a decision so we have next steps to improve docs.

[chrisdostert]

1. If we are only having Reference docs and Training docs; can we not simplify and literally just have a template w/ the boilerplate form of a "Training Doc"?
2. I wonder if we can formalize this more "Given a reader with knowledge, skills and abilities a, b, c"; such as a formal section of the template that links to other "Trainings" it assumes you've completed etc...

[gunnarg-remitly]

I'd say given a policy, it would suggest things like "adopt a template for document types" and "make a checklist for document prs".

I really like the idea of trainings linking to other trainings in some sort of progression, "next steps", "prerequisites", etc.

I'd advocate for keeping the policy high level, and letting the policy drive the particulars of implementation.

I'd also advocate for keeping the process light, and mainly providing a paved and brightly lit road towards making the docs we want to see.

[psamaan]

I don't think we are saying we have only 1 type of training doc. This distinction is at the top level of the doc type tree, underneath that there may be sub-types. For example I would like to see Training Doc sub-types of Guide and Tutorial, each with a different template/form, similar to Tensorflow docs. Guide docs may be use-case driven as per @lmarszal's comment, while Tutorial docs are progressive in difficulty. This is all not part of the current proposal, and would be additive to it.

[chrisdostert]

Personally I think I like the idea of starting with 2 types and then adding more over time if we see value. There's not meaningful difference between guide and tutorial for me; I feel like it's somewhat arbitrary and not clear benefit to separating those concepts; it just adds to the places I have to look. Like @gunnarg-remitly mentioned, trainings could reference other trainings as pre-requisites or next-steps

[gunnarg-remitly]

I think I'd be happy just deciding on the direction we want to take the training docs.

Alternatively, refactor the “Training” documentation to be a manual with a tutorial cookbook. is certainly something I'm behind. I mainly want a little more structure/direction in that realm of documentation, because I think it's where the accessibility to the reference docs comes from.

[gunnarg-remitly]

The specific deliverable I want out of the proposal to refactor the documentation is a direction + a number of issues that can be assigned/tracked, so we can distribute making progress on documentation