Creating documentation guidelines for plugins #3378
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
contents/docs/plugins/build/index.md
Outdated
|
|
||
| To ensure that plugins are useful to others, we require that plugins submitted to [our integration library](/integrations) follow some guidelines. This helps us ensure we describe plugins correctly and give other users the information they need to use a plugin correctly. | ||
|
|
||
| We encourage you to add more info, screenshots, etc., if you feel it is useful, but as a minimum we require that plugins submitted to [hey@posthog.com](mailto:hey@posthog.com?subject=Submit%20Plugin%20to%20Repository&body=Plugin%20GitHub%20link%3A) answer the follow questions. |
There was a problem hiding this comment.
How does someone submit this info...just as text in the email?
There was a problem hiding this comment.
My bad. Intended to be added as a README.MD. My fault for editing things out of order.
|
|
||
| We encourage you to add more info, screenshots, etc., if you feel it is useful, but as a minimum we require that plugins submitted to [hey@posthog.com](mailto:hey@posthog.com?subject=Submit%20Plugin%20to%20Repository&body=Plugin%20GitHub%20link%3A) answer the follow questions. | ||
|
|
||
| - What does your plugin do? |
There was a problem hiding this comment.
These look pretty good, another suggestion (for you to consider - I appreciate keeping short list is pretty important).
- Who is this plugin designed for?
contents/docs/plugins/build/index.md
Outdated
|
|
||
| ## Adding your plugin to PostHog | ||
|
|
||
| Once you've built your own plugin, you can submit it our [integration library](/integrations). This means everyone else can use your plugin too, including users on PostHog Cloud. Here's how: |
There was a problem hiding this comment.
This is not actually the case. We also have to enable the plugin for everyone on cloud.
There is another step - but I'm not sure we need to tell users that.
There was a problem hiding this comment.
Moved this comment to the end and softened the language, so it's clearer this is a choice that we will make during review.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Changes
Who else hates it that all of our plugins have very variable documentation, often failing to describe core features (SalesForce), configuration options (First Time Event Tracker) or their requirements and how to set them up correctly (basically all of them)?
I know I do, especially after writing 70+ pages for the upcoming Plugins > Apps shift, where I needed to describe what all the plugins do, requirements, etc.
So, I've written some documentation guidelines and added them to the Build Your Own section of the plugins docs. I've also moved some other bits around in the plugins docs, such as moving the information about plugin chains and integrations with external systems from the Build Your Own section to the Plugin Overview. The Build Your Own section now only contains information about how to build your own plugin.
Separately, I've added some of these guidelines and info to the plugin starter kit readme.
What are the guidelines I'm proposing? Well, I don't want this to be too process-driven and make plugins harder work for anyone. So, we're requiring that plugins which users want to submit to our official library must have a README.md which answers the following questions...
This will result in a 1000% improvement in the usefulness of future plugin documentation. It's quantifiable!
Checklist