From 303e66f00669bd7f7e82a430d92164fa7012dccd Mon Sep 17 00:00:00 2001 From: Melissa McEwen Date: Thu, 14 May 2020 16:56:41 -0500 Subject: [PATCH 1/2] Update README.md --- README.md | 59 +++++++++---------------------------------------------- 1 file changed, 9 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 195ad6f..1114fb0 100644 --- a/README.md +++ b/README.md @@ -24,48 +24,29 @@ Ideas1: - New Glitch features - If you had to make a choice about a tool or framework recently, how did you decide? -## Team -- Editor: Melissa McEwen -- Copyeditors: Ryan Khosravi -- Advisor: Margarita Noriega -- Tech reviewers: members of the engineering team as needed - ## Writing your post -### Proposal -Create a Clubhouse story using the Dev.to template. Assign to Melissa. We'll work with you on topic and due date. - ### Outline -If you already have a process that works for you, go for it! Otherwise I strongly recommend writing a post outline and submitting it to Melissa for review. You can do this on the Clubhouse story. +If you already have a process that works for you, go for it! Otherwise I strongly recommend writing a post outline and submitting it to #editorial for review ### Drafting -You're welcome to use whatever tools work for you. I strongly recommend using a tool like [Hemingway](http://www.hemingwayapp.com/), which encourages concise engaging writing. Make sure you follow the checklist in the Appendix. +You're welcome to use whatever tools work for you. I strongly recommend using a tool like [Hemingway](http://www.hemingwayapp.com/) or [Vale](https://errata.ai/vale-server/), which can catch basic errors. See the Appendix for a helpful Writing checklist. -Submit drafts as Markdown via pull request at 🔒[devto-posts](https://github.com/glitchdotcom/devto-posts) and make sure it's [associated with the Clubhouse ticket](https://help.clubhouse.io/hc/en-us/articles/360023113972-How-do-I-associate-a-branch-to-a-Story-).. For example my post about Testing I would create a new file called test.md, add my post draft, and create a branch. Then submit a pull request for that branch to master. If you're new to GitHub, Melissa can help you with a personalized tutorial. +Submit drafts as Markdown via pull request at 🔒[devto-posts](https://github.com/glitchdotcom/devto-posts). For example my post about Testing I would create a new file called test.md, add my post draft, and create a branch. Then submit a pull request for that branch to master. The [Pull Request template](https://github.com/glitchdotcom/devto-posts/blob/master/.github/PULL_REQUEST_TEMPLATE.md) has a checklist for the rest of the process. At this point don't worry about embeds, pictures or any other formatting. -After your draft is ready assign the PR to Melissa to review. - ### Automated feedback -When you submit a pull request on 🔒[devto-posts](https://github.com/glitchdotcom/devto-posts) you'll get some automated checks via GitHub Actions. You can see the results in the "checks" area of the Pull Request. -- [Vale](https://errata-ai.github.io/vale/) looks for common mistakes and gives some _optional_ writing advice. -- [Link Checker](https://github.com/marketplace/actions/link-checker) visits the links in your post to make sure they work. +When you submit a pull request on 🔒[devto-posts](https://github.com/glitchdotcom/devto-posts) you'll get some automated checks via GitHub Actions. You can see the results in the "checks" area of the Pull Request. Currently [Link Checker](https://github.com/marketplace/actions/link-checker) visits the links in your post to make sure they work. -### Feedback -For the feedback process we'll give you big picture pointers on the structure and content of your piece. We will not directly edit your piece at this stage. After preparing feedback the editor will reassign the Pull Request and story to you. When you incorporate the feedback, please reassign to Melissa for review. +### Adding images/embeds and sharing with #editorial +At this stage, put your post into Dev.to in the Glitch org (see appendix) and add any formatting, images, and code blocks you'd like. Dev.to will give you a helpful draft link which you should share to the #editorial channel on Slack. -#### Technical Review -The editor may add a reviewer for highly technical subjects if they are outside their experitise. +Make sure what's in Dev.to is synced with the Markdown file in the PR. -### Copyediting -At this stage, put your post into Dev.to in the Glitch org (see appendix) and add any formatting and code blocks you'd like. Assign back to the editor. - -We'll add UTM params to your links, and add images if you haven't. We'll also update the post in the [devto-posts](https://github.com/glitchdotcom/devto-posts) repo to make sure the link checker runs. - -### Ready to post! -Next we'll workshop Tweets and social media images. Feel free to leave this to us. When we publish we'll promote on our Dev Twitter and the homepage. +## Editing a post +If you're asked to review a post, we recommend doing the "review" option on the GitHub pull request. Simple copy edits (spelling, grammar) can be done as simple edits to the MarkDown file. Larger feedback can be done as comments. For a helpful resource for editing posts see the "Writing checklist" in the Appendix. ## Appendix ### Code Review @@ -95,29 +76,7 @@ To add posts to the Glitch org on Dev.to you'll need to join it. Sign up for the - Conclusion - A CTA (call to action) sentence like "remix this and tweet us what you made" - Glitch boilerplate (see section in appendix) - - ### Publishing checklist - This publishing checklist is intended for use in pull requests -``` -### Pre-publishing - -- [ ] Outline -- [ ] Schedule on Shared Content Calendar -- [ ] Feedback -- [ ] Copy editing -- [ ] Images -- [ ] Tags -- [ ] Add UTM tags to links -- [ ] Post to the #editorial channel in Slack the day before publishing - -### Post-publishing -- [ ] Schedule Tweet and notify #community -- [ ] Post to #marketing-all and #social-content -- [ ] Update Shared Content Calendar -- [ ] Post to forum (optional) - -``` ### Glitch boilerplate From b164c84b9c21b7daa9dd559e3edae3eaf48080be Mon Sep 17 00:00:00 2001 From: Melissa McEwen Date: Thu, 14 May 2020 19:20:51 -0500 Subject: [PATCH 2/2] Update README.md --- README.md | 52 +++++++++++++++++++++++++++++++++++----------------- 1 file changed, 35 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 1114fb0..2c69b95 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ Glitch on Dev.to ================= -This is a guide for writing blog posts for the [Glitch org on Dev.to](https://dev.to/glitch/). Testing. +We'd love to have you post on the [Glitch org on Dev.to](https://dev.to/glitch/). To create some consistency around posts we've created this handy guide. ## Content on Dev.to Basic standards: @@ -26,27 +26,27 @@ Ideas1: ## Writing your post -### Outline -If you already have a process that works for you, go for it! Otherwise I strongly recommend writing a post outline and submitting it to #editorial for review - ### Drafting -You're welcome to use whatever tools work for you. I strongly recommend using a tool like [Hemingway](http://www.hemingwayapp.com/) or [Vale](https://errata.ai/vale-server/), which can catch basic errors. See the Appendix for a helpful Writing checklist. +You're welcome to use whatever tools work for you. I strongly recommend using a tool like [Hemingway](http://www.hemingwayapp.com/) or [Vale](https://errata.ai/vale-server/), which can catch basic errors. See Writing Tips and Publishing Checklist in the Appendix. + +### Getting Feedback +The post should be proofread by someone other than you. It can be anyone at Glitch and if you can't think of anyone post in the #editorial slack channel and someone will help you out. -Submit drafts as Markdown via pull request at 🔒[devto-posts](https://github.com/glitchdotcom/devto-posts). For example my post about Testing I would create a new file called test.md, add my post draft, and create a branch. Then submit a pull request for that branch to master. The [Pull Request template](https://github.com/glitchdotcom/devto-posts/blob/master/.github/PULL_REQUEST_TEMPLATE.md) has a checklist for the rest of the process. +Share your post as a dev.to draft link OR if you want revisioning you can use one of these tools: -At this point don't worry about embeds, pictures or any other formatting. +- [A PR in the DevTo posts Github](https://github.com/glitchdotcom/devto-posts) +- [DraftIn](https://draftin.com/) -### Automated feedback -When you submit a pull request on 🔒[devto-posts](https://github.com/glitchdotcom/devto-posts) you'll get some automated checks via GitHub Actions. You can see the results in the "checks" area of the Pull Request. Currently [Link Checker](https://github.com/marketplace/actions/link-checker) visits the links in your post to make sure they work. +though you'll have to copy and paste the results back and forth to Dev.to. -### Adding images/embeds and sharing with #editorial -At this stage, put your post into Dev.to in the Glitch org (see appendix) and add any formatting, images, and code blocks you'd like. Dev.to will give you a helpful draft link which you should share to the #editorial channel on Slack. -Make sure what's in Dev.to is synced with the Markdown file in the PR. +### Publishing +Once you've gotten feedback and made the edits, post the final draft in the #editorial Slack channel. If there is no objection after a day, go ahead and add a card to [Shared Content Calendar](https://trello.com/b/YpRhWeeT/shared-content-calendar) in the "Dev.to" column assigned to you with the date you want to publish. +On that day, publish your post by setting `published: true` in Dev.to. Then post to the #Community channel with the URL so GlitchDevs can tweet it out. -## Editing a post -If you're asked to review a post, we recommend doing the "review" option on the GitHub pull request. Simple copy edits (spelling, grammar) can be done as simple edits to the MarkDown file. Larger feedback can be done as comments. For a helpful resource for editing posts see the "Writing checklist" in the Appendix. +## Giving Feedback/ Editing a post +For a helpful resources for editing posts see the "Writing tips", "Code Review", and "Publishing checklist" in the Appendix. ## Appendix ### Code Review @@ -63,19 +63,37 @@ We do not have a strict code review process or standards, but we like to see: ### Joining the Dev.to Glitch org To add posts to the Glitch org on Dev.to you'll need to join it. Sign up for the Dev.to account if you don't have one and DM Melissa on Slack to join. -### Writing checklist +### Writing tips - Introduction - - a clear "what's this post about" sentence that tells the reader what they'll learn if they read on. + - a clear "what's this post about" thesis sentence that tells the reader what they'll learn if they read on. - a link to Glitch - keep it short! - Subheaders (H2s) - if it's a tutorial, these should be the steps, otherwise these should be the main points - - first sentence under subhead should introduce the section + - first sentence under subhead should introduce the section, connect it to main thesis - we love links, make sure to link whenever possible - no sub subheads (like h3s, h4s) - Conclusion + - A good conclusion should "conclude" the "what's this post about sentence". For example if the "what's this post about" sentence is "Learning how to automate email can make your life easier" it should conclude with a sentence about how the post did make the reader's life easier. - A CTA (call to action) sentence like "remix this and tweet us what you made" - Glitch boilerplate (see section in appendix) + + ## Publishing Checklist + ### Pre-publishing +- Schedule on [Shared Content Calendar](https://trello.com/b/YpRhWeeT/shared-content-calendar) (add a card in the dev.to column assigned to yourself with a due date) +- Get review from at least one person +- Add tags (check out [here](https://dev.to/tags) for popular tags, we recommend 3 popular tags) +- Add [boilerplate](https://devto-handbook.glitch.me/) +- Post the Dev.to draft in the #editorial channel in Slack at least one day before publishing + +### Publishing +- Change front matter `published` value to `published: true` on Dev.to + +### Post-publishing +- Post in #community to share the URL so we can tweet it out +- Once it's Tweeted, share the Tweet to #social-content +- Update Shared Content Calendar +- Post to [forum](https://support.glitch.com/) (optional) ### Glitch boilerplate