✍️ @Zedd's Blog

[zchisholm]

Hi and welcome to Content Lab! Here is a self paced guide to ensure you get feedback as you publish your technical blog.

Resources:

• Previous workshop recording
• Previous blog posts

Timeline:

• 📋 Dec 1st have an outline and open up issue
• 📰 Dec 8th have rough draft in
  • Mentor reviews by 12/15
• [ ] Dec 15th-20th turn in final draft

📋 Blog Outline: Write your outline in the issue directly

Requirements

Questions to consider:

• Who’s reading this? Where are they in your dev journey? What do they need to know before they can dive into this story?
• If people could leave with just one action, what would it be?
• Were there surprises or alternative problem solving you want to give a heads up to?

Sample Topics for your blog post

• Creating tests for Stripe/Cicero/Twilio
• Using Vuetify and V-cards
• Debugging a PR test failure affecting entire codebase and creating an issue for it
• System Design/Architecture design for caching capability
• Implementing Text to Speech
• Configuring secrets for APIs in codespaces
• Building Actions for [security|community|CI| etc]

Example Outlines

What makes good documentation on open source?

• Could this be a list? (3 pieces of documentation thats easy to check for and add to the project to add immediate value?
• What inspired you from the Tech documentation workshop?
• What would you help encourage other first time contributors to do?
• Is a learning curve for everyone? And whats the balance between good documentation and too much documentation? Choice architecture
• What is each space used for? Wiki vs Discussion vs Pages
• How do we search and find? Reference: https://blackgirlbytes.dev/conquering-the-fear-of-contributing-to-open-source Reference issue/PR for photos Conclusion: Documentation is always changing, will always be needed`

To Do: when you complete the requirements, add "outline ready" label on your issue

• [x] Identify your topic from one of the PRs approved
• [x] Outlining bullet points of blog roadmap
• [x] Is your blog a List, Survey, or demo?
• [x] Which Visuals or Diagram or Code snippets will you add
• [x] References to resources

📰 Blog Rough draft: Format into a google doc

Questions to answer across draft

• Why is this helpful for a reader?
• What problem does this help them solve?
• What kind of experience should the reader have or that you will provide so they’re up to speed
• What larger problem is this solving?
• Were there other ways of solving this problem - what made you choose the one that you did?
• What were the positive tradeoffs? (Did it save time? Save hours? Was more secure?)
• What is the best way to present the content (i.e. code snippets, graphics) ?
• What additional resources can they provide the reader if they want more information?
• Is there a call to action?

To do: when you complete the requirements, add "draft ready" label on your issue

• [x] intro paragraph
• [x] context of Amplify
• [x] paragraph on problem
• [ ] paragrph compare your solution
• [ ] paragraph impact your solution
• [x] Less than 600 words
• [x] Drop link to your google doc (with permissions for edits) in review issue

[zchisholm]

Outline/Rough

More of a demo Plan to add visuals of PRT that I've create and maybe others that I find. Markdown snippets too

How a Pull Request Template Can Improve Your Team’s Workflow

Introduction

What is a Pull Request Template?

Pull request (PR) templates are predefined markdown files that provide structure for contributors when creating a pull request. They ensure consistent, clear, and complete documentation of changes, making them crucial for efficient collaboration in software projects.

Background or Context

Why PR Templates Matter in Software Development

PR templates streamline the review process, improve communication, and reduce errors in both open-source and large team projects. They help developers provide the necessary information for successful reviews, such as testing steps, related issues, and potential impacts, ultimately enhancing code quality and project management.

Key Concepts or Features

Key Features of Pull Request Templates

1. Consistency: Ensures that each PR includes necessary information in a uniform format.
2. Clarity: Guides contributors to provide clear explanations of changes, testing, and related issues.
3. Efficiency: Helps reviewers understand changes quickly, reducing review time and enabling faster merges.
4. Accountability: Encourages best practices and minimizes potential errors.

Practical Application / How-To

How to Create a Pull Request Template

1. Create a .github directory: Add a .github folder in your repository's root if it doesn't already exist.
2. Add a PULL_REQUEST_TEMPLATE.md file: Inside .github, create a file named PULL_REQUEST_TEMPLATE.md.
3. Structure the template: Include:
   • Title: Brief, descriptive title of the change.
   • Description: Explain the change, its necessity, and impact.
   • Related Issues: Reference related issues using #issue-number.
   • Testing: Outline steps to test the changes.
   • Checklist: Add tasks like running tests or updating docs.
4. Save and commit: Commit the PR template file to the repository for use.

Example Template:

# Pull Request Title

## Description
- What changes were made?
- Why are they necessary?
- Any relevant context?

## Related Issues
- Closes #[issue-number]

## Testing
- [ ] Describe how to test the changes.

## Checklist
- [ ] Code has been tested
- [ ] Documentation updated
- [ ] Follows project coding standards

Common Pitfalls or FAQs

Common Mistakes to Avoid with Pull Request Templates

Avoid These Mistakes with PR Templates

1. Incomplete Information: Not filling out all sections can slow reviews.
2. Generic Templates: Tailor templates to include relevant sections for your team’s needs.
3. Ignoring the Template: If it’s consistently overlooked, simplify or revise it.
4. No Regular Updates: Review and update templates periodically to maintain relevance.

Conclusion

Wrapping Up: Final Thoughts on Pull Request Templates

Summarize content

Pull request templates are a fundamental part of a well-structured development process. They bring consistency, clarity, and efficiency to code reviews, ensuring that contributors provide all necessary information upfront. By reducing errors and improving communication, PR templates ultimately help maintain high-quality code and smoother project management. Don’t underestimate the impact of a good template—start creating or refining yours today!

Call to Action

Where to Learn More or Get Started

Share docs, examples, and actionable steps to get started.

Ready to improve your repository’s workflow? Implement a pull request template in your project and encourage your team to use it consistently. For more guidance, check out GitHub’s documentation on pull request templates.

Interested in open source? Look for projects that use pull request templates and contribute to see them in action!

[Alex-is-Gonzalez]

Make sure to replace your boiler template with your actual Blog topic.

For example, you could write about how to add Pull Request templates to your workflow

[zchisholm]

For some reason, I'm unable to add a label. Maybe I'm doing it wrong. I tried selecting the labels on the right-hand side, but it doesn't work.

[zchisholm]

Link: https://docs.google.com/document/d/1IdMMlu77iponmCwgLeuv1g-BEk8C-UuMrInVfqnn_nI/edit?usp=sharing