Deployment model selection, cumulative authoring, ++ #1445
Conversation
shainaraskas
changed the title
shainaraskas
requested review from
Mpdreamz,
florent-leborgne and
colleenmcginnis
Co-authored-by: Jan Calanog <jan.calanog@elastic.co>
| ## Configure a space-level landing page [space-landing-page] | ||
| ```{applies_to} | ||
| stack: ga | ||
| serverless: unavailable | ||
| ``` | ||
| ```` | ||
| % I think we wanted to not specify stack here |
There was a problem hiding this comment.
@florent-leborgne @colleenmcginnis I think we talked about only having the serverless: unavailable tag here. wyt
I can extend to the areas that follow the same rule based on what we decide (couple of additional instances in this PR)
There was a problem hiding this comment.
Thanks for getting this started @shainaraskas! I was only able to get through the pages in the Contribute section so far. I tried to scope my review to the accuracy and clarity of information. I didn't leave comments related to style or grammar.
I might have introduced some scope creep in the pages other than deployment model and cumulative authoring 🙈 but it was helpful to read through all the content together to get a full picture. I'll open separate issues for those comments so this PR doesn't become unmanageable.
|
|
||
| To contribute to earlier versions of the Elastic Stack, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses AsciiDoc as it's authoring format. | ||
| ### Contribute to elastic.co/guide |
There was a problem hiding this comment.
Maybe swap the sections on elastic.co/guide and elastic.co/docs since more people will probably come here for information on elastic.co/docs?
|
|
||
| This helps readers understand which parts of the content apply to their own ecosystem and product versions, without needing to switch between different versions of a page. | ||
| In Docs V3, a single branch is published per repository. This branch is set to `main` (or `master`) by default, but it is possible to instead publish a different branch by changing your repository's deployment model. You might want to change your deployment model so you can have more control over when content added for a specific release is published. |
There was a problem hiding this comment.
Or "to the public docs site"?
| In Docs V3, a single branch is published per repository. This branch is set to `main` (or `master`) by default, but it is possible to instead publish a different branch by changing your repository's deployment model. You might want to change your deployment model so you can have more control over when content added for a specific release is published. | |
| In Docs V3, a single branch is published to production per repository. This branch is set to `main` (or `master`) by default, but it is possible to instead publish a different branch by changing your repository's deployment model. You might want to change your deployment model so you can have more control over when content added for a specific release is published. |
There was a problem hiding this comment.
This branch is set to
main(ormaster) by default
Technically main is the only default. For any repos that use master we specify it in the same way we would specify 9.0 or 9.1.
| * It's a **documentation** problem: [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) *or* [Fix it myself](locally.md). You can open sensitive issues in our [internal repo](https://github.com/elastic/docs-content-internal/issues/new/choose). | ||
| * It's a **build tool (docs-builder)** problem: [Open a bug report](https://github.com/elastic/docs-builder/issues/new?template=bug-report.yaml) |
There was a problem hiding this comment.
| * It's a **documentation** problem: [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) *or* [Fix it myself](locally.md). You can open sensitive issues in our [internal repo](https://github.com/elastic/docs-content-internal/issues/new/choose). | |
| * It's a **build tool (docs-builder)** problem: [Open a bug report](https://github.com/elastic/docs-builder/issues/new?template=bug-report.yaml) | |
| * For **documentation** problems: [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) *or* [Fix it myself](locally.md). You can open sensitive issues in our [internal repo](https://github.com/elastic/docs-content-internal/issues/new/choose). | |
| * For **build tool (docs-builder)** problems: [Open a bug report](https://github.com/elastic/docs-builder/issues/new?template=bug-report.yaml) |
|
|
||
| * Make the **documentation** better --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) | ||
| * Make our **build tool (docs-builder)** better --> [Start a docs-builder discussion](https://github.com/elastic/docs-builder/discussions) | ||
| * Make the **documentation** better: [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml). You can open sensitive issues in our [internal repo](https://github.com/elastic/docs-content-internal/issues/new/choose). |
There was a problem hiding this comment.
If we plan to keep these docs public, maybe this would be more accurate?
| * Make the **documentation** better: [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml). You can open sensitive issues in our [internal repo](https://github.com/elastic/docs-content-internal/issues/new/choose). | |
| * Make the **documentation** better: [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml). Elastic employees can open sensitive issues in our [internal repo](https://github.com/elastic/docs-content-internal/issues/new/choose). |
docs/contribute/locally.md
Outdated
There was a problem hiding this comment.
I wonder if we should add an optional section to this page about running a build locally to check for and troubleshoot build errors before pushing up to GitHub. It's not required, but it would be helpful to have it documented somewhere so we can point to it when contributors ask. This could be done in a follow-up PR.
| * `main` can contain code and docs for unreleased versions that we don’t want to publish yet. | ||
| * The versioning scheme and release cadence of the product associated with a repository can vary, and it can be inconsistent to have the docs associated with a certain version live in a different branch than the code. | ||
|
|
||
| If you choose this publication model for your repository AND that repository includes {{serverless-short}} or {{ecloud}} documentation, you will need to make sure that {{serverless-short}}- and {{ecloud}}-related changes are also backported to the `current` branch in order to be published on time. |
There was a problem hiding this comment.
It might be confusing to say the current branch because the actual branch name is probably not going to be current (it would be 9.0, 9.1, etc).
| If you choose this publication model for your repository AND that repository includes {{serverless-short}} or {{ecloud}} documentation, you will need to make sure that {{serverless-short}}- and {{ecloud}}-related changes are also backported to the `current` branch in order to be published on time. | |
| If you choose this publication model for your repository AND that repository includes {{serverless-short}} or {{ecloud}} documentation, you will need to make sure that {{serverless-short}}- and {{ecloud}}-related changes are also backported to the branch that is publishing to the public docs site. |
| * Specify which is the `next` branch for the repository. The branch defined as `next` publishes docs internally to [staging-website.elastic.co/docs](http://staging-website.elastic.co/docs) | ||
| * Setting this branch to the next version branch in line is a good practice to preview docs change for an upcoming version. | ||
| * Otherwise, keeping it set to `main` is also an option since this is where the content is initially developed and merged. This is the default. | ||
| 2. [Add new triggers to the `docs-build` CI integration](/configure/deployment-models.md#ci-configuration). |
There was a problem hiding this comment.
This needs to be updated and merged before the PR in step 1 can be merged so it might be better to put this one first. See elastic/logstash#17701 for more specific step-by-step instructions that I followed recently to set this up.
|
|
||
| ## Workflow 2: Tagged deployment | ||
|
|
||
| Learn how to make updates in the continuous deployment model, where the repo is publishing docs from a specific `version` branch. |
There was a problem hiding this comment.
| Learn how to make updates in the continuous deployment model, where the repo is publishing docs from a specific `version` branch. | |
| Learn how to make updates in the continuous deployment model, where the repo is publishing docs from a specific version branch. |
|
|
||
| ### Where to make docs changes [make-changes-td] | ||
|
|
||
| Initiate the changes by opening a PR against the `main` branch of the repo. The changes will be backported to the relevant version branches as detailed below. |
There was a problem hiding this comment.
To me this reads like backporting will happen automatically... maybe:
| Initiate the changes by opening a PR against the `main` branch of the repo. The changes will be backported to the relevant version branches as detailed below. | |
| Initiate the changes by opening a PR against the `main` branch of the repo, and backport the changes to the relevant version branches as detailed below. |
|
|
||
| ### More examples [more-examples-td] | ||
|
|
||
| We’ve prepared a few end-to-end examples to help in [Figma](https://www.figma.com/design/CZDl0szuGsQfJhFpnwJVWS/Applies_to-Docs-V3?node-id=0-1&p=f&t=lBPrvde0k5zg9U0E-0). |
There was a problem hiding this comment.
I'm not sure we should link to this from the docs since the UX is not necessarily going to be the same. I think linking from the Official Docs sets the wrong expectations.
This PR makes information related to our deployment models and cumulative authoring approach more visible and does some accuracy edits
Key changes
Introduce hints about deployment models ("Branches in V3") and refactor cumulative documentation callout.
Pages refactored to pivot from stack version to platform, plus minor changes
Cleanup, minor changes, warnings
TODO (future PRs)
/versions/pages