External Collaboration Guidelines

Overview

This guide covers the external collaboration processes, focusing on working with marketing teams and coordinating Subject Matter Expert (SME) reviews.

Working with Marketing Teams

Writing Technical Blog Posts

Process for Requesting Marketing to Publish a Blog Post

Once you have a pretty good first draft, open a marketing request in Monday.

• For the "Title", use the format: Blog Post: Suggested title of the post

• In Request Type - Choose Content & Design to reserve time for their edits and creating the top image.

• In the Notes section, it's a good idea to request that they don't publish until you've had a chance to review & approve the final version, as sometimes their editors make edits that make our content inaccurate.

• Fill in the rest of the form as appropriate

After you submit the form, relevant marketing members will coordinate with you via Monday.

In general, the marketing team takes care of getting the draft into WordPress, creating a top image for you and editing the post to maximize reach and SEO.

You can also optionally, add/edit the content directly to the WordPress blog site yourself if you have permissions (most of the doc members do) via the process described below. If you don't have permissions and you need them, sync w/ Kevin Lynch to get permissions.

Authoring in the WordPress Blog Site

WordPress Admin: https://cloudinary.com/blog/wp-admin/

Mickey A's recording of everything to know about authoring in the WP site: https://cloudinary.zoom.us/rec/share/9BkfLTDsECmAXfQGvnNBMyoFJT_MFsmUj6vUAVP4J9aZG_KUPworwaC_c_daJUKv.x_yo7n0JQr-d_WTV?startTime=1649976309000

Subject Matter Expert (SME) Reviews

Working with SME Reviewers

• Most feature PRs should get both a dev (and/or other SME - i.e. relevant product manager, CS engineer, etc) and doc review.

• For big issues, it generally makes sense to get all the dev/SME reviews implemented first, and only then ask for a doc review of the updated content.

• If one or more of your SME reviewers aren't familiar/comfortable with GitHub, create the PR, and then copy-paste the doc preview to a GoogleDoc & have them comment there so you can implement the changes. (Usually helpful to also put these on staging so the reviewer can see what it will really look like). In this case, you should still get a doc review & approval in the PR itself.

Cross-Team Coordination for SDKs and Add-ons

SDK Development Coordination

When working on new SDK documentation:

Make sure the JIRA Epic for the new SDK includes tasks (for SDK/front-end team) to update welcome email, dashboard quick links, and onboarding widget. Give them the main doc page for the SDK framework that they should link to.

For more information, see Adding a New SDK or Integrations Guide

Add-on Development Coordination

Every new Add-on should have an Epic in JIRA. That epic should include user stories for:

• Docs Write Snippet - (JIRA that's generated from the Dev Snippet issue) write text for snippet & provide dev with the link they should use to the docs. This JIRA is in our doc sprint. When done, copy-paste the text & link to the CLD issue & then mark the Docs issue as done.

• Snippet Graphics - Prepare svg icon & a graphic for within the snippet

For more information, see Documenting New Add-ons

Documentation Feedback Handling

On Call Schedule

Team rotation for handling incoming documentation feedback and urgent issues.

Slack Handling

Process for managing feedback received through Slack channels:

1. If feedback includes non-Cloudinary email address and doesn't appear to be spam, start by creating a support ticket as described below.

2. If feedback includes valid & concrete suggestions for improving docs, create an issue:

   • If there's a non-Cloudinary email: Open issue from created support ticket to create linkage. Set issue type as Doc Feedback. Make sure the summary includes the actual doc improvement to do, paste a copy of the original feedback content in the description (along with any other relevant info).
   • If no email/Cloudinary email: Use Slack issue button to create the issue. Change the summary to what you think should be done in the docs. If Cloudinary email/name supplied, then when the issue is handled, we should get back to the Cloudinary employee to let them know it's implemented (or ask for approval before deploy for more complex improvements.)

3. Always add a reply to the Slack message:

   • Include links to created support tickets and/or issues
   • Reply saying nothing needs to be done, just so it's clear the entry has been addressed
   • Tag people in our team or others if the feedback isn't relevant for support/issues but is worthy of discussion

Support Ticket Management

Quick instructions for managing feedback through support system:

First Entry

• Paste the full contents of the feedback as the first entry - keep it internal
• Fill in the email of the customer as the submitter - assuming it finds the user, select them
• If you plan to answer yourself, assign to yourself. If you prefer tech support answer, then change to tech support
• Submit as New

If Tech Support Should Answer

• Add another internal entry with suggestions of what you'd like the support engineer to highlight from our docs (i.e. specific links, etc) or questions you'd like them to ask
• Submit as Open

If You Want to Answer Directly

• Add your answer, set as public entry. Make sure to thank them for submitting their feedback, highlight relevant doc points, ask questions, or let them know if you plan to improve something based on their feedback. (Or if it was a very small fix request - write them only after you've made the fix & let them know it's fixed thanks to their feedback). Always conclude with letting them know that the doc/developer experience is really important to us and we welcome them to submit additional feedback or suggestions for the docs at any time.

• Sign it with your own name (Your job title is automatically appended)

• Submit as Pending

• Keep an eye on whether you get an answer from the customer

About the Documentation Feedback Form Code

Testing Doc Feedback in Development Environment

1. In docs.haml add true || to the GTM line (~line 50): ruby if true || !Rails.env.development?

2. In main.js, comment out lines ~257-260: javascript // if (currentUrl.includes("docs-dev.cloudinary.com/documentation") // || currentUrl.includes("staging.cloudinary.com/documentation")) { // env = 'https://cld-doc-feedback-staging.herokuapp.com/'; // prod = false; // }

Frontend

Form validation and submission handling integrated with site JavaScript.

ReCaptcha

Spam protection integrated into feedback form submission process.

Backend

• Heroku path: [Documentation needed]
• Git project: [Documentation needed]