Feat: Improve ADaaS documentation #178
Conversation
🌟 EkLine ReviewerHello! I’m here to help improve your docs. I’ve reviewed your pull request, and left in-line suggestions for quick fixes. For details, visit the Analytics Page. For questions or feedback, please email support@ekline.io. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
Published docs preview URL: https://devrev-preview-94cf0cfc-4b53-4c64-85a2-a99b696c77cb.docs.buildwithfern.com |
|
Published docs preview URL: https://devrev-preview-beb4c33f-fd03-497c-873d-17d019251d1a.docs.buildwithfern.com |
|
Published docs preview URL: https://devrev-preview-4705dd7b-d5f4-47a7-9728-5f27c46aef14.docs.buildwithfern.com |
|
Published docs preview URL: https://devrev-preview-ada29d70-1e0f-4fa8-911f-ddf6a39544b2.docs.buildwithfern.com |
|
Published docs preview URL: https://devrev-preview-f13bbb9d-37ae-42c7-a227-637c1d4d700a.docs.buildwithfern.com |
|
Published docs preview URL: https://devrev-preview-baa0d4bd-104b-44a9-950d-ef838453fd54.docs.buildwithfern.com |
|
Published docs preview URL: https://devrev-preview-62d5f37b-e918-43b2-818a-cb3bab3a6a83.docs.buildwithfern.com |
|
Published docs preview URL: https://devrev-preview-eb1bc397-61b3-4666-8305-79e17e42f980.docs.buildwithfern.com |
|
Published docs preview URL: https://devrev-preview-8afbbb89-8459-45ab-a5b7-6428cefa25f6.docs.buildwithfern.com |
|
Published docs preview URL: https://devrev-preview-5d5427d0-1a95-43be-b63e-9c4dc6ce9520.docs.buildwithfern.com |
|
Published docs preview URL: https://devrev-preview-f508e024-2aaa-49bd-af18-5e83690bbac0.docs.buildwithfern.com |
|
Published docs preview URL: https://devrev-preview-0daa28d2-a44a-4c3f-8dd1-197ac7265cd8.docs.buildwithfern.com |
|
Published docs preview URL: https://devrev-preview-8aa278f7-796d-4abf-afc5-69c1a21de37b.docs.buildwithfern.com |
|
Published docs preview URL: https://devrev-preview-2081bca4-d2dc-4428-9d1b-7d2ad86e9387.docs.buildwithfern.com |
patricijabrecko
changed the title
|
Published docs preview URL: https://devrev-preview-a7c40bbe-e1d9-4a1e-8976-f19a9f7fc8b9.docs.buildwithfern.com |
|
Published docs preview URL: https://devrev-preview-ee9ea88b-938b-43bb-a0c7-12c0631cb3c9.docs.buildwithfern.com |
| It is recommended you consider the following points before you start the implementation: | ||
|
|
||
| 1. Examine the domain model of the external system and identify available and required fields for its objects. | ||
| 2. Examine DevRev's domain model - use the specification given [here](https://github.com/devrev/airdrop-recipe-manager/blob/main/v2/devrev_metadata/devrev_metadata_docs.md). |
There was a problem hiding this comment.
Is this public? If not, can we make it public?
|
|
||
| ## Triggering event | ||
| In the external sync unit extraction phase, the snap-in is expected to obtain a list of external | ||
| sync units that it can extract from the external system API and send it to Airdrop in its response. |
There was a problem hiding this comment.
Should we remove the extra newline?
We haven't defined what an "external sync unit" is. Lets define it or speak in more general terms.
There was a problem hiding this comment.
One paragraph above defines external sync unit :)
| @@ -0,0 +1,15 @@ | |||
| Extraction generally involves four sequential phases: | |||
|
|
|||
| 1. external sync units extraction (only on initial import), | |||
There was a problem hiding this comment.
I would mark 1) as a pre-extraction phase. It is totally different and lets not batch it together with others.
| 'signalColor': '#7d7f7c', | ||
| 'signalTextColor': '#7d7f7c' | ||
| }}}%% | ||
| actor user as User |
There was a problem hiding this comment.
Did we keep the old diagrams in some other file?
|
|
||
| ### Sync unit | ||
|
|
||
| A _sync unit_ is one connection instance to an external system (for example SalesForce, Freshdesk, Zendesk). |
There was a problem hiding this comment.
"A sync unit is one self encompassing unit of data that is synced to an external system. Examples: "
- Jira project
- SalesForce "organization"?
- ...
|
|
||
| An _initial import_ consists of the following phases: | ||
|
|
||
| 1. External sync units extraction |
There was a problem hiding this comment.
"External sync units extraction" as there is no sync unit yet defined.
| It is recommended you consider the following points before you start the implementation: | ||
|
|
||
| 1. Examine the domain model of the external system and identify available and required fields for its objects. | ||
| 2. Examine DevRev's domain model - use the specification given [here](https://github.com/devrev/airdrop-recipe-manager/blob/main/v2/devrev_metadata/devrev_metadata_docs.md). |
There was a problem hiding this comment.
| 2. Examine DevRev's domain model - use the specification given [here](https://github.com/devrev/airdrop-recipe-manager/blob/main/v2/devrev_metadata/devrev_metadata_docs.md). | |
| 2. Examine DevRev's domain model given [here](https://github.com/devrev/airdrop-recipe-manager/blob/main/v2/devrev_metadata/devrev_metadata_docs.md). |
| @@ -0,0 +1,41 @@ | |||
| When your snap-in is ready for use by you or other organizations, publish it to the DevRev marketplace. Before starting the publication process, ensure your snap-in is deployed to your organization. If you need a refresher, refer to the [instructions](/snapin-development/adaas/development-guide/getting-started#publishing-the-snap-in) for deploying your snap-in. | |||
|
|
|||
| ### 1. Create marketplace listing | |||
There was a problem hiding this comment.
You can use the <Steps> component here if you'd like. https://buildwithfern.com/learn/docs/content/components/steps
|
Published docs preview URL: https://devrev-preview-7060c439-46de-460e-b74c-97c3acde9966.docs.buildwithfern.com |
There was a problem hiding this comment.
Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit
EkLine
🚫 [EkLine] reported by reviewdog 🐶
'directory' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'dm' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'Fixed Fields' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'enhancement' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'Fixed Fields' should use sentence-style capitalization. (EK00037)
Consider using 'customer' instead of 'Rev'. (EK25033)
Consider using 'customer' instead of 'Rev'. (EK25033)
🚫 [EkLine] reported by reviewdog 🐶
'feature' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'Fixed Fields' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'group' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'incident' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'issue' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'Fixed Fields' should use sentence-style capitalization. (EK00037)
Where possible, do not structure sentences in future tense. Use present tense instead. (EK00005)
Consider using 'customer' instead of 'Rev'. (EK25033)
🚫 [EkLine] reported by reviewdog 🐶
'link' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'linkable' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'Fixed Fields' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'meeting' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'microservice' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'Fixed Fields' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'object_member' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'opportunity' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'Fixed Fields' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'money' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'product' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'Fixed Fields' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'revu' should use sentence-style capitalization. (EK00037)
Consider using 'customer' instead of 'Rev'. (EK25033)
Suggestions:
- Where possible, do not structure sentences in future tense. Use present tense instead. (EK00005)
- Consider using 'customer' instead of 'Rev'. (EK25033)
Consider using 'customer' instead of 'Rev'. (EK25033)
🚫 [EkLine] reported by reviewdog 🐶
'runnable' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'Fixed Fields' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'sysu' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'tag' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'task' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'Fixed Fields' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'test_custom_type' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'Fixed Fields' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'ticket' should use sentence-style capitalization. (EK00037)
🚫 [EkLine] reported by reviewdog 🐶
'Fixed Fields' should use sentence-style capitalization. (EK00037)
Consider using 'customer' instead of 'rev'. (EK25033)
Consider using 'customer' instead of 'Rev'. (EK25033)
| | `started_by_id` | reference -> [#category:user] | | User that started the conversation | | ||
| | `tags` | reference (collection) -> [#record:tag] | | Tags associated with the object | | ||
| | `title` | text | | Title of the conversation object | | ||
| | `turing_active` | bool | | Whether Turing is active on the conversation. Will be true when Turing is active and false when it stops responding or when a dev user responds to the conversation. | |
There was a problem hiding this comment.
Where possible, do not structure sentences in future tense. Use present tense instead. (EK00005)
| | `turing_active` | bool | | Whether Turing is active on the conversation. Will be true when Turing is active and false when it stops responding or when a dev user responds to the conversation. | | |
| | `turing_active` | bool | | Whether Turing is active on the conversation. Is true when Turing is active and false when it stops responding or when a dev user responds to the conversation. | |
|
|
||
| --- | ||
|
|
||
| ## custom_link |
|
|
||
| **Capabilities:** Can Extract, Can Load | ||
|
|
||
| ### Fixed Fields |
|
|
||
| --- | ||
|
|
||
| ## custom_part |
|
|
||
| **Capabilities:** Can Extract, Can Load, Can Subtype | ||
|
|
||
| ### Fixed Fields |
|
Published docs preview URL: https://devrev-preview-e24a5e3e-fa0b-409f-8149-0b7cd78afeef.docs.buildwithfern.com |
This pull request aims to improve the documentation for developing Airdrop snap-ins.
New sections were added to describe the development journey step-by-step and existing sections, especially those covering the extraction phases, have been expanded.
Related issues: