-
Notifications
You must be signed in to change notification settings - Fork 3.9k
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
📚 Update documentation best practices #3870
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good, some comments.
* how to build and run the code locally & via Docker | ||
* any other information needed for local iteration | ||
|
||
### Changelogs |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should have people use this format for consistency:
Changelog
| Version | Date | Pull Request | Subject |
| :------ | :-------- | :----- | :------ |
| 0.2.0 | 20XX-05-XX | [PR2#](https://github.com/airbytehq/airbyte/pull/PR2#) | description |
| 0.1.0 | 20XX-04-XX | [PR#](https://github.com/airbytehq/airbyte/pull/PR#) | description |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@sherifnada Abhi and I are adding the changelog into the connector documentation.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
done
Below are some best practices related to each of these. | ||
|
||
### READMEs | ||
Every module should have a README containing: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe a section on setting up the source/destination in the UI, explaining the fields?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this kind of info goes into the docs/
documentation (public facing) so we probably shouldn't duplicate it? WDYT?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agree. If this is just GH facing then I'm fine with that.
When creating a PR, follow the naming conventions depending on the change being made: | ||
|
||
* New connectors: “🎉 New source or destination: <name>” e.g: `🎉 New Source: Okta` | ||
* New features: “🎉<Source or Destination> <name>: <feature description> E.g: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add a small note about core features?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
done
Co-authored-by: Abhi Vaidyanatha <abhi@airbyte.io>
…byte into sherif/docs-best-practices
What
Updates the "updating documentation" section of the docs to add best practices and guidlines for documentation.