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.

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

Developer guide cleanup #67782

Closed
stacey-gammon opened this issue May 29, 2020 · 4 comments · Fixed by #67764
Closed

Developer guide cleanup #67782

stacey-gammon opened this issue May 29, 2020 · 4 comments · Fixed by #67764

Comments

@stacey-gammon
Copy link
Contributor

stacey-gammon commented May 29, 2020

Overview

  • Remove outdated sections the reference angular and/or legacy plugins
  • Rearrange the outline.
  • Migrate contributing guide over.

Sections to be removed or updated.

Ideally they would be updated, but to start, I think they do more harm than good, and should just be removed. Then the relevant teams can work on adding relevant content back in.

The following sections are outdated or specific to legacy plugin development and/or angular:

  • Communicating with Elasticsearch
  • development-uiexports.
  • Modules and Autoloading
  • Managing dependencies
  • Base path stuff

Restructuring the format

Previously separate into two categories:

  • Core development
  • Plugin development

The content in these two sections aren't mutually exclusive and I think "core" is not clear at this point to a new developer.

New outline suggestion:

  • Getting started
  • Development best practices
  • Available apis & services
  • Developing directly to the Kibana repo
  • Developing plugins externally
  • Advanced & in-depth

Here is some examples of the content under each section:

  • Getting started
    • Development environment
      • Running elasticsearch
      • Adding sample data
    • Terminology & concepts
      • Plugin, application, registry, etc
  • Development best practices (some of these will be required to be checked in to the repo).
    • Don't couple to core
    • Localization
    • Typescript
    • etc
  • Available apis & services (maybe should be part of the API docs/plugin readmes, or just link to them?)
    • Core services
      • basePath
    • Security
    • Visualize
    • Add data
  • Developing directly to the Kibana repo
    • Using github
    • Creating pull requests
    • Running tests
    • Documentation
    • Managing dependencies
    • Best practices that are required for code to get into the Kibana repo
  • Developing plugins externally
    • Running functional tests
  • Advanced & in-depth
    • Es snapshots

cc @joshdover @gchaps @KOTungseth

Related

@stacey-gammon
Copy link
Contributor Author

@joshdover you commented in the PR:

Developing directly to the Kibana repo
Developing plugins externally

Maybe it makes more sense to have a generic "Developing plugins" section that is applicable to both scenarios and a "Developing plugins in the Kibana repo" section that is specific to 1st party plugins.

Otherwise I feel like these two sections just overlap a lot.

Where would I put content that is only relevant to developing plugins externally in that case? For instance, this section says Every project or plugin should have its own FunctionalTestRunner config file.. That is not true for internal plugins.

And the stuff above about developing directly to the kibana repo isn't relevant for external developers. They don't have to know about our github workflow, or submitting pull requests, or how to update our asciidoc docs if they added or changed a user facing feature.

The common stuff I was planning to put under best practices, available services, and getting started -> Terminology & concepts.

It might make sense to have a generic "Developing plugins" section, but it shouldn't contain any information that is relevant to a person who is not developing a plugin, but instead editing a plugin for the purpose of creating a feature. Otherwise I think they would gloss over it.

@gchaps
Copy link
Contributor

gchaps commented May 29, 2020

This outline works well. The new titles make it easier for users to understand what content is in each section. I'm a big fan of Getting Started and Best practices sections.

@elasticmachine
Copy link
Contributor

Pinging @elastic/kibana-docs (Team:Docs)

@stacey-gammon
Copy link
Contributor Author

Latest proposal from #67764:

docoutline

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants