Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add more details on developer documentation #126674

Merged
merged 12 commits into from
Mar 3, 2022
Merged

Add more details on developer documentation #126674

merged 12 commits into from
Mar 3, 2022

Conversation

stacey-gammon
Copy link
Contributor

  • Moves documentation best practices to it's own page, now linked to from the generic best practices page.
  • Expands on documentation information, adding things like REST APIs and end user documentation
  • Adds a note at the top of the external, legacy developer guide pointing to the new one for internal folks, and the repo for external folks.
  • Removes the section about developer documentation in the legacy guide as it's no longer valid.
  • Moves contributing section ahead of Key concepts and Tutorials.

Screen Shot 2022-03-02 at 8 51 05 AM

@stacey-gammon stacey-gammon added release_note:skip Skip the PR/issue when compiling release notes v8.2.0 labels Mar 2, 2022
@stacey-gammon stacey-gammon force-pushed the 2022-03-01-fix-dev-docs-link branch from a6a3ccf to 67694f4 Compare March 2, 2022 15:16
danielmitterdorfer
danielmitterdorfer reviewed Mar 3, 2022
View reviewed changes
Copy link
Member

@danielmitterdorfer danielmitterdorfer left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the PR! It looks fine to me. I wasn't sure whether we should go to that level of detail here but left a few suggestions. Feel free to accept or ignore them. :)

dev_docs/contributing/documentation.mdx Outdated Show resolved Hide resolved
dev_docs/contributing/documentation.mdx Outdated Show resolved Hide resolved
dev_docs/contributing/documentation.mdx Outdated Show resolved Hide resolved
dev_docs/contributing/documentation.mdx Outdated Show resolved Hide resolved
dev_docs/contributing/documentation.mdx Outdated Show resolved Hide resolved
dev_docs/contributing/documentation.mdx Outdated Show resolved Hide resolved
dev_docs/contributing/documentation.mdx Outdated Show resolved Hide resolved
dev_docs/contributing/documentation.mdx Show resolved Hide resolved
dev_docs/contributing/documentation.mdx Outdated Show resolved Hide resolved
docs/developer/index.asciidoc Outdated Show resolved Hide resolved
stacey-gammon and others added 8 commits March 3, 2022 08:24
@stacey-gammon @danielmitterdorfer
Update dev_docs/contributing/documentation.mdx
26c3b8d 
Co-authored-by: Daniel Mitterdorfer <danielmitterdorfer@users.noreply.github.com>
@stacey-gammon @danielmitterdorfer
Update dev_docs/contributing/documentation.mdx
3b1905e 
Co-authored-by: Daniel Mitterdorfer <danielmitterdorfer@users.noreply.github.com>
@stacey-gammon @danielmitterdorfer
Update dev_docs/contributing/documentation.mdx
ce06294 
Co-authored-by: Daniel Mitterdorfer <danielmitterdorfer@users.noreply.github.com>
@stacey-gammon @danielmitterdorfer
Update dev_docs/contributing/documentation.mdx
032c136 
Co-authored-by: Daniel Mitterdorfer <danielmitterdorfer@users.noreply.github.com>
@stacey-gammon @danielmitterdorfer
Update dev_docs/contributing/documentation.mdx
78ccf43 
Co-authored-by: Daniel Mitterdorfer <danielmitterdorfer@users.noreply.github.com>
@stacey-gammon @danielmitterdorfer
Update dev_docs/contributing/documentation.mdx
94b7cc9 
Co-authored-by: Daniel Mitterdorfer <danielmitterdorfer@users.noreply.github.com>
@stacey-gammon
Address review feedback
70d7865
@stacey-gammon
Merge branch '2022-03-01-fix-dev-docs-link' of github.com:stacey-gamm…
bd486ad 
…on/kibana into 2022-03-01-fix-dev-docs-link
@stacey-gammon
Copy link
Contributor Author

Thanks for your feedback @danielmitterdorfer! I am all for any feedback that improves the readability of the guide, so it is much appreciated.

danielmitterdorfer
danielmitterdorfer approved these changes Mar 3, 2022
View reviewed changes
Copy link
Member

@danielmitterdorfer danielmitterdorfer left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for iterating! LGTM

jportner
jportner reviewed Mar 3, 2022
View reviewed changes
dev_docs/contributing/documentation.mdx Outdated Show resolved Hide resolved
dev_docs/contributing/documentation.mdx
- Use `@throws` when appropriate.
- Use `@beta` or `@deprecated` when appropriate.
- Use `@removeBy {version}` on `@deprecated` APIs. The version should be the last version the API will work in. For example, `@removeBy 7.15` means the API will be removed in 7.16. This lets us avoid mid-release cycle coordination. The API can be removed as soon as the 7.15 branch is cut.
- Use `@internal` to indicate this API item is intended for internal use only, which will also remove it from the docs.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We use @public in several places, it's not clear to me what the distinction is, perhaps we should mention that here too?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't officially recommend using @public, it's a convention that I think only the core team uses. I think it'd be great to use, but only if we had ci checks to ensure all public APIs were labeled appropriate, and fail if not. Otherwise it can't be trusted to be accurate.

@stacey-gammon @jportner
Update dev_docs/contributing/documentation.mdx
ed3224f 
Co-authored-by: Joe Portner <5295965+jportner@users.noreply.github.com>
@stacey-gammon stacey-gammon enabled auto-merge (squash) March 3, 2022 17:14
@kibana-ci
Copy link
Collaborator

💚 Build Succeeded

Metrics [docs]

✅ unchanged

History

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

@stacey-gammon stacey-gammon merged commit e1ac939 into elastic:main Mar 3, 2022
@kibanamachine
Copy link
Contributor

Friendly reminder: Looks like this PR hasn’t been backported yet.
To create backports run node scripts/backport --pr 126674 or prevent reminders by adding the backport:skip label.

@kibanamachine kibanamachine added the backport missing Added to PRs automatically when the are determined to be missing a backport. label Mar 7, 2022
@kibanamachine
Copy link
Contributor

Friendly reminder: Looks like this PR hasn’t been backported yet.
To create backports run node scripts/backport --pr 126674 or prevent reminders by adding the backport:skip label.

1 similar comment
@kibanamachine
Copy link
Contributor

Friendly reminder: Looks like this PR hasn’t been backported yet.
To create backports run node scripts/backport --pr 126674 or prevent reminders by adding the backport:skip label.

@jportner jportner added the backport:skip This commit does not require backporting label Mar 9, 2022
@kibanamachine kibanamachine removed the backport missing Added to PRs automatically when the are determined to be missing a backport. label Mar 9, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jportner jportner jportner left review comments

@danielmitterdorfer danielmitterdorfer danielmitterdorfer approved these changes

Assignees
No one assigned
Labels
backport:skip This commit does not require backporting release_note:skip Skip the PR/issue when compiling release notes v8.2.0
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@stacey-gammon @kibana-ci @kibanamachine @danielmitterdorfer @jportner