etcd techdoc analysis

[dwelsch-esi]

First draft of the etcd analysis and implementation.

Contributes to: #191

[jbogarthyde]

Overall looks great. A few typos and some minor rewrite suggestions.

[jbogarthyde]

Maybe define product vs project doc concept in intro, as a general organizational principle.

[dwelsch-esi]

Added to the recommendations outline in the intro.

[jbogarthyde]

The rest seems to imply that the two paths point to a named "Operations Guide" and "Developer Guide" -- if so, maybe make that explicit, and clarify that the audience for each section should be clearly stated.
Provide sample TOC?

[dwelsch-esi]

Changed ToC to re-add Operator and Developer guides.

[thisisobate]

@dwelsch-esi @nate-double-u I just updated the website section as planned. Feel free to take a look

[jberkus]

In general, this is everything we were trying to get done in 2022. So overall a huge improvement.

I've got a couple questions/comments though, the biggest ones being:

1. Need to understand the rationale of not including contributor docs in the main docs.
2. Role split for admins

[jberkus]

Etcd does have release notes in the repository. Here, are you saying also copy those to the user documentation?

[dwelsch-esi]

I'm saying documentation best practice in my opinion would be to move the release notes into the documentation and take them out of the repo. My position as a technical writer is that release notes are part of the product documentation. It boils down to user role -- the release notes should be accessible to the software users -- in the case of etcd, developers and operators.

That said, this is an OSS project; these are suggestions, not mandates; and there could very well be reasons to leave the release notes where they are. Moving them might require effort better spent elsewhere, for example, or this project's contributors are used to looking for them in the repo. A graduated project should have a justification for doing anything that differs from documentation best practice, but one or two minor variations don't constitute a reason to condemn otherwise good documentation.

If it's OK with you, I'm going to leave this recommendation in and the community can evaluate and act on it in the context of the project. Feel free to close the issue as "will not fix" if that's the project consensus.

Finally, more important than where the release notes (or any other source of information) lives is the principle that it be a single source of truth: Don't maintain two copies of the release notes in two locations; instead, provide a link to them from the second (and any other) locations.

[jberkus]

What's the benefit of moving contributor documentation to the main repository? I understand having it in its own section, but aren't there benefits to having it in the more readable & structured format supplied by doc publishing?

[dwelsch-esi]

Again, it's a best practice designed to separate content for different user roles. By analogy with commercial software, you wouldn't put (presumably internal) developer documentation in your user manuals. I realize that in OSS there's no proprietary information to keep hidden, but there are other reasons to maintain that separation. A big one in my experience is to avoid confusing new users, who don't yet have a good mental model of the product and are relying on the documentation to build that understanding.

That said, in OSS projects the lines are sometimes blurred between contributors and certain users. And there are sometimes good reasons to put contributor docs on the website; your readability example is one. I recommend that If you do put contributor documentation in the tech docs, clearly label it as such and isolate it from the user documentation.

[jberkus]

It's worth splitting Admin into two sub-roles: (a) Admin using Etcd embedded in Kubernetes (b) admin using Etcd on its own.

[dwelsch-esi]

That's an excellent suggestion. I'll need to collaborate with a contributor who understands the differences between the sub-roles in order to update the implementation plan.

[jberkus]

See comment above

[dwelsch-esi]

Yup, I wasn't aware of the release notes when I wrote this item. We can remove this as an issue.

[jberkus]

Same comment as on etcd-implementation

[dwelsch-esi]

Addressed @jberkus 's review comments. Excellent questions; I've tried to address them from a tech writer's perspective. Let me know what you think.

[dwelsch-esi]

I'm saying documentation best practice in my opinion would be to move the release notes into the documentation and take them out of the repo. My position as a technical writer is that release notes are part of the product documentation. It boils down to user role -- the release notes should be accessible to the software users -- in the case of etcd, developers and operators.

That said, this is an OSS project; these are suggestions, not mandates; and there could very well be reasons to leave the release notes where they are. Moving them might require effort better spent elsewhere, for example, or this project's contributors are used to looking for them in the repo. A graduated project should have a justification for doing anything that differs from documentation best practice, but one or two minor variations don't constitute a reason to condemn otherwise good documentation.

If it's OK with you, I'm going to leave this recommendation in and the community can evaluate and act on it in the context of the project. Feel free to close the issue as "will not fix" if that's the project consensus.

Finally, more important than where the release notes (or any other source of information) lives is the principle that it be a single source of truth: Don't maintain two copies of the release notes in two locations; instead, provide a link to them from the second (and any other) locations.

[dwelsch-esi]

Again, it's a best practice designed to separate content for different user roles. By analogy with commercial software, you wouldn't put (presumably internal) developer documentation in your user manuals. I realize that in OSS there's no proprietary information to keep hidden, but there are other reasons to maintain that separation. A big one in my experience is to avoid confusing new users, who don't yet have a good mental model of the product and are relying on the documentation to build that understanding.

That said, in OSS projects the lines are sometimes blurred between contributors and certain users. And there are sometimes good reasons to put contributor docs on the website; your readability example is one. I recommend that If you do put contributor documentation in the tech docs, clearly label it as such and isolate it from the user documentation.

[dwelsch-esi]

That's an excellent suggestion. I'll need to collaborate with a contributor who understands the differences between the sub-roles in order to update the implementation plan.

[dwelsch-esi]

Yup, I wasn't aware of the release notes when I wrote this item. We can remove this as an issue.

[nate-double-u]

Thanks for this @dwelsch-esi, and thanks for the reviews everyone!