Ksatter handbook 4583 weekly doc update process (#5279)

* Add community PR guidelines * Fix broken formatting on Community Contribution process * Correct formatting issues Fixed incorrect casing on headings, corrected incorrect heading indicators and moved review section out of the process flow. * Add links to community PR process Added links to product DRIs and community contribution guidelines * Change Communitiy contributions > Pull requests * formatting and typo fixes Made some formatting and typo fixes. * Update community.md - Added additional information on PRs that will not be merged - Formatting cleanu[ * Update community.md * Add weekly documentation update to handbook/community * Update README.md * Update handbook/community.md Co-authored-by: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com> * Update handbook/community.md Co-authored-by: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com> * Update handbook/community.md Co-authored-by: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com> * Update handbook/community.md Co-authored-by: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com> * Update handbook/community.md Co-authored-by: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com> * Update handbook/community.md Co-authored-by: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com> * Update handbook/community.md Co-authored-by: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com> Co-authored-by: Mike Thomas <mthomas@fleetdm.com> Co-authored-by: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com>
2022-04-26 12:34:49 -05:00
parent 6fb4f5b21c
commit ecd155c16f
2 changed files with 36 additions and 6 deletions
@@ -57,6 +57,8 @@ The Fleet handbook is the central guide for how we run the company. As part of o

 [Pull requests](./community.md#pull-requests)

+[Updating docs and FAQ](./community.md#updating-docs-and-faq)
+
 [Fleet swag](./community.md#fleet-swag)

 ### 🚀 Engineering
@@ -190,17 +190,18 @@ graph TD;

 ## Pull requests

-When community members contribute to Fleet, the most important thing is to show them we value their time and effort. We need to get eyes on community pull requests quickly (within one business day) and get them merged or give feedback as soon as possible.
+The most important thing when community members contribute to Fleet is to show them we value their time and effort. We need to get eyes on community pull requests quickly (within 1 business day) and get them merged or give feedback as soon as we can.

 ### Process for managing community contributions

-The Community Engagement DRI is responsible for keeping an eye out for new community contributions and either getting them merged if possible or getting the right eyes on them if a review is needed. 
+The Community Engagement DRI is responsible for keeping an eye out for new community contributions and either getting them merged in if possible and get the right eyes on them if they need to be reviewed. 

 Each business day, the Community Engagement DRI will check open pull requests to:

 1. Check for new pull requests (PRs) from the Fleet community. 
 2. Approve and merge any community PRs that are ready to go.
-3. Make sure there aren't any existing community PRs waiting for a follow-up from Fleet. 
+3. Make sure there aren't any existing community PRs waiting for followup from Fleet. 
+

 #### Identify community contributions

@@ -212,6 +213,7 @@ When a new pull request is submitted by a community contributor (someone not a m
    - Things that generally don't need additional review:
        - Minor changes to the docs.
        - Small bug fixes.
+
        - Additions or fixes to the Standard Query Library (as long as the SQL works properly and is attributed correctly).
    - If a review is needed:
        - Request review from the [Product DRI](./product.md#product-dris). They should approve extensive changes and new features. Ask in the #g-product channel in Fleet's Slack for more information.
@@ -226,7 +228,6 @@ Community contributions are awesome, and it's important that the contributor kno

 While each team member is responsible for monitoring their active issues and pull requests, the Community Engagement DRI will check in on pull requests with the `:community ` label daily to make sure everything is moving along. If there's a comment or question from the contributor that hasn't been addressed, reach out on Slack to get more information and update the contributor. 

-
 #### Merge Community PRs

 When merging a pull request from a community contributor:
@@ -253,7 +254,7 @@ For PRs that aren't ready to merge:

 - Thank the contributor for their hard work and explain why we can't merge the changes yet.
 - Encourage the contributor to reach out in the #fleet channel of osquery Slack to get help from the rest of the community.
- Offer a code review and coaching to help get the PR ready to merge (see note below).
+- Offer code review and coaching to help get the PR ready to go (see note below)
 - Keep an eye out for any updates or responses.

 > Sometimes (typically for Fleet customers), a Fleet team member may add tests and make any necessary changes to merge the PR. 
@@ -262,9 +263,36 @@ If everything is good to go, approve the review.

 For PRs that will not be merged:

- Thank the contributor for their effort and explain why their suggestions won't be merged.
+- Thanks the contributor for their effort and explain why the changes won't be merged.
 - Close the PR.

+## Updating Docs and FAQ
+
+When someone asks a question in a public channel, it's pretty safe to assume that they aren't the only person looking for an answer to the same question. To make our docs as helpful as possible, the Community team gathers these questions and uses them to make a weekly documentation update. 
+
+Our goal is for every question to be answered with a link to the docs and/or result in a documentation update.
+
+### Tracking
+
+When responding to a question or issue in the [#fleet](https://osquery.slack.com/join/shared_invite/zt-h29zm0gk-s2DBtGUTW4CFel0f0IjTEw#/) channel of the osquery Slack workspace, push the thread to Zapier using the `TODO: Update docs` Zap. This will add information about the thread to the [Slack Questions Spreadsheet](https://docs.google.com/spreadsheets/d/15AgmjlnV4oRW5m94N5q7DjeBBix8MANV9XLWRktMDGE/edit#gid=336721544). In the `Notes` field, you can include any information that you think will be helpful when making weekly doc updates. That may be something like:
+
+- Proposed change to the documentation.
+- Documentation link that was sent as a response.
+- Link to associated thread in [#help-oncall](https://fleetdm.slack.com/archives/C024DGVCABZ).
+
+### Making the updates
+
+Every week, the Community Engagement DRI will:
+
+- Create a new `Weekly Doc Update` issue on Monday and add it to the [Community board](https://github.com/orgs/fleetdm/projects/36).
+- Review the Slack Questions Spreadsheet and ensure that any necessary updates to the documentation are made. 
+    - Update the spreadsheet to indicate what action was taken (Doc change, FAQ added, or None) and add notes if need be. 
+- Set up a single PR to update the Docs. 
+    - In the notes, include a list of changes made as well as a link to the related thread. 
+- Bring any questions to DevRel Office Hours (time TBD).
+- Submit the PR by the end of the day on Thursday. 
+- Once the PR is approved, share in the [#fleet channel](https://osquery.slack.com/archives/C01DXJL16D8) of Osquery Slack Workspace and thank the community for being involved and asking questions. 
+
 ## Fleet swag

 We want to recognize and congratulate community members for their contributions to Fleet. Nominating a contributor for Fleet swag is a great way to show our appreciation.