Add best practices for applies_to
#1614
Conversation
colleenmcginnis
added
documentation
Co-authored-by: Brandon Morelli <[email protected]>
|
@bmorelli25 @georgewallace these page are ready (enough) for review:
|
Co-authored-by: florent-leborgne <[email protected]>
| @@ -1,61 +1,24 @@ | |||
| # Applies to | |||
There was a problem hiding this comment.
It could be helpful to add a link to the Badge placement page from the https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/1614/syntax/applies#inline-annotations section.
|
|
||
| In [elastic.co/docs](https://elastic.co/docs) (Docs V3), we write docs cumulatively regardless of the [branching strategy](/contribute/branching-strategy.md) selected. This means that in our Markdown-based docs, there is no longer a new documentation set published with every minor release: the same page stays valid over time and shows version-related evolutions. | ||
|
|
||
| :::{note} |
There was a problem hiding this comment.
I think this big note gives the opening paragraph a disjointed feeling, consider removing the note and just having a cohesive prose introduction that immediately establishes both the concept and its scope.
| Nothing changes for our ASCIIDoc-based documentation system, that remains published and maintained for the following versions: Elastic Stack until 8.x, ECE until 3.x, ECK until 2.x, etc. | ||
| ::: | ||
|
|
||
| ## Reader experience |
There was a problem hiding this comment.
The image is perfect ✨ but I don't think this prose does it justice— consider making the intro text more concrete and to the point, with more connective tissue to the illustration
|
|
||
| ## Contributor experience | ||
|
|
||
| With cumulative documentation, there is a single "source of truth" for each feature, which helps us to maintain consistency, accuracy, and maintainability of our documentation over time, and avoids "drift" between multiple similar sets of documentation. |
There was a problem hiding this comment.
I think this could be more concrete upfront, something like
With cumulative documentation, instead of updating different versions of the same page for each minor, you update one markdown file throughout the entire major version cycle. This eliminates the need to maintain multiple copies of the same content and manage backports across version branches. This helps us to maintain consistency, accuracy, and maintainability of our documentation over time, and avoids "drift" between multiple similar sets of documentation.
|
|
||
| With cumulative documentation, there is a single "source of truth" for each feature, which helps us to maintain consistency, accuracy, and maintainability of our documentation over time, and avoids "drift" between multiple similar sets of documentation. | ||
|
|
||
| As new minor versions are released, we want users to be able to distinguish which content applies to their own ecosystem and product versions without having to switch between different versions of a page. |
There was a problem hiding this comment.
Isn't this the reader experience?
| * **Every paragraph/section**: Only tag when the context or applicability changes from what has been established earlier on the page. | ||
| * **Unversioned products**: For products where all users are always on the latest version (like serverless), you don't need to tag workflow changes if the product lifecycle is unchanged. | ||
|
|
||
| ### How dynamic tags work [how-do-these-tags-behave-in-the-output] |
There was a problem hiding this comment.
I kinda feel like wherever the when to/when not to stuff lives, we should move "How dynamic tags work" before the those sections, as understanding the system should precede usage guidelines.
Co-authored-by: Liam Thompson <[email protected]>
| :::: | ||
|
|
||
| :::{warning} | ||
| Do **not** create a new column just for versions. |
There was a problem hiding this comment.
@florent-leborgne what do you think? This idea came from you in a Slack thread.
There was a problem hiding this comment.
@shainaraskas do you have an example where it would make the most sense to create a new column? I haven't seen anything that would require this yet.
| % FOR THE REVIEWER: SHOULD THESE ACTUALLY BE THE SAME? | ||
| % In the existing docs (https://elastic.github.io/docs-builder/contribute/cumulative-docs/#section-or-inline-contexts-situational), | ||
| % we say to treat Stack/Serverless and deployment types differently. | ||
| % Should we? | ||
| ## Section applicability differs from page applicability [page-section-varies] |
There was a problem hiding this comment.
generally, deployments have "applicability" info and stack/serverless have "availability" info. difficult to find examples for both. I see what florent is saying but I think we do treat them differently because what we are communicating is slightly different most of the time
deployments vs. stack versions is a clearer distinction for contributors, most likely, so it's kind of a shorthand. we could spell that out maybe?
| % FOR THE REVIEWER: SHOULD THESE ACTUALLY BE THE SAME? | ||
| % In the existing docs (https://elastic.github.io/docs-builder/contribute/cumulative-docs/#section-or-inline-contexts-situational), | ||
| % we say to treat Stack/Serverless and deployment types differently. | ||
| % Should we? | ||
| ## Section applicability differs from page applicability [page-section-varies] |
There was a problem hiding this comment.
we could split on "applicability" vs "availability" hypothetically, and do better on pages like this:
https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/pki (pki auth "unavailable" on ech / serverless)
| % FOR THE REVIEWER: WHICH IS CORRECT? | ||
| % The existing docs and the "real" example in the wild use different strategies. | ||
| % Do we include `stack: ga` in the section annotation or not? |
There was a problem hiding this comment.
I vote for the standalone unavailable (calling out differences only) but this is not a problem that arises for me much so open to the will of the people
| For example, on the [Lens](https://www.elastic.co/docs/explore-analyze/visualize/lens) page we added information | ||
| about a new option that was added to Serverless in GA and the Elastic Stack in GA in 9.1.0. | ||
| Even though it is added to Serverless, an unversioned product, in the same lifecycle state as the page-level annotation, | ||
| we still include an inline annotation to make it clear that this is not only available in the Elastic Stack. |
There was a problem hiding this comment.
I don't think we should do this. my biggest reason is dev contributors. they have tunnel vision for the change they're making, and serverless is often inconsequential to them. we should only need them to put the relevant stack label.
if we need both labels to show, we should do it with code logic.
| Since the page's frontmatter already includes `serverless: ga`, there is no need to label the added content. | ||
|
|
||
| % FOR THE REVIEWER: IS THIS TRUE? | ||
| ::::::{important} |
There was a problem hiding this comment.
would consider pulling this out of a note so it's all just together as guidance
| page from the Elastic Stack in 9.1.0 and from Serverless around the same time. | ||
| Since this this functionality is still available before 9.1.0, we need that content to continue to be | ||
| available to users on Elastic Stack earlier versions while communicating to users on newer versions | ||
| that it is no longer available. |
There was a problem hiding this comment.
could link down to exceptions for tech preview/beta functionality here
| % I couldn't find an actual example of this scenario. | ||
| % For example, we removed the <something> functionality that was described on the [<page>](#) page | ||
| % from the Elastic Stack in 9.1.0. | ||
| % Since this this functionality is still available in 9.0.0, we need that content to continue to be |
There was a problem hiding this comment.
something "no longer true" sticking around is used on the write thread pool here. excuse the fucked up formatting
https://www.elastic.co/docs/reference/elasticsearch/configuration-reference/thread-pool-settings
| ::::{image} ./images/example-code-block-callout.png | ||
| :screenshot: | ||
| :::: |
There was a problem hiding this comment.
the ideal scenario is [feature] was introduced in [version]
but our inline badges look terrible in sentences ...
but the takeway is that I don't think the current recommended prose is clear
There was a problem hiding this comment.
are we using this anymore? I kind of miss it
There was a problem hiding this comment.
Any suggestions on where to put it?
There was a problem hiding this comment.
It's most closely aligned with examples. Maybe could just deep link into examples instead of writing them up separately. It's just another view of the accepted patterns and I think helps people think outside of the box if their scenario isn't covered
Co-authored-by: shainaraskas <[email protected]>
Co-authored-by: shainaraskas <[email protected]>
Closes https://github.com/elastic/docs-content-internal/issues/55
Restructures and adds to the docs on how to write cumulative documentation.
I started collecting examples from across Slack and GitHub where the Docs team has been discussing how we should approach cumulative documentation in different scenarios. This will add a best practices doc outlining what I've found. There are some situations where I've found conflicting or incomplete advice. In those cases, I'll try to get consensus. 🙃
Approach
Splits content on writing cumulative documentation into several pages with different goals and/or audiences based on conversations I've had over the last couple months with dev teams, other writers, and other docs contributors:
applies_toto find the list of valid values without having to dig through all the information in Syntax > Applies to.I also moved the content in Versions and types closer to the docs on cumulative documentation.
For reviewers
Where there was conflicting guidance in GitHub/Slack or docs contributors used inconsistent strategies across the live docs, I tried to make a judgement call. If you you disagree or have another approach we should consider, feedback/input is very welcome! I tried to highlight some of the spiciest takes 🌶️ with a code comment:
% FOR THE REVIEWER.My focus in this PR is to capture the nuances of cumulative documentation and providing guidance on as many scenarios as possible. I haven't had a chance to reread the content for copy editing purposes. If anyone wants to do an editing pass they are welcome to edit and commit changes directly instead of adding MANY suggestions.