✍️ @_joey_ma's Blog

[joey-ma]

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

This is a draft to be worked on further.*

Resources:

• Previous workshop recording
• Previous blog posts

Timeline:

• 📋 Week 4: Create an outline by 3/2
• 📰 Week 7: Rough draft due by 3/16
  • Mentor reviews by 3/30
• Week 9: Final version due 4/7

📋 Blog Outline:

I think I'm going to go with Idea No. 2 and save Idea No. 1 for another day, but just keeping it here as notes (it was the first idea that came up).

Idea No. 1:

Topic: What makes good documentation?

Inspired by Documentation for Open Source Projects

Start

Intro paragraph:

• What is documentation?
• The documentation system
• documentation: the structure by Daniele Procida

Middle

Helpful examples/concepts:

• Tutorials: Learning-oriented
  • Svelt Tutorials
  • React Tutorial: Tic-Tac-Toe
• How-to Guides: Problem-oriented
  • Building a web app with Parcel
• Explanation: Understanding-Oriented
  • React: Reacting to input with state
  • Spotify: Authorization Guides
  • Vue Introduction
• References: Information-Oriented
  • git-scm

End

Summary:

• Know your personal preference
• Knowing the different types of documentations could help you approach different styles of docs more effectively
• When writing your own documentation, help create clear, helpful documentation for your audience

Additional Resources:

• Sphinx for Python Documentation
  Intro to Sphinx for Python Documentation

Idea No. 2:

Topic: TDD: Creating tests for Stripe

Inspired by Test Driven Development with Stripe
Also this is an issue that I'm working on and what I'm hoping to be more familiar with

Start

Intro paragraph:

• What is TDD? (short intro)
• What is Stripe?
• Let's write some tests for Stripe!

Middle

• An overview of Stripe API. Components of Stripe API?
• How to write a test? How to Test Stripe API?
  also happens to be a question on Stackoverflow
  • Some popular libraries (just a short mention)
    https://www.browserstack.com/guide/top-javascript-testing-frameworks
    • Selenium
    • Cypress
    • Jest
    • Playwright
  • Unit Test
    • One of the many benefits of using Stripe, a technology that's relied upon by millions of companies of all sizes, is that it is battle-tested. Stripe systems operate with 99.99%+ uptime and are highly scalable and redundant.
      https://status.stripe.com/
      
    • For this example, we'll focus on the integration test. Leave a comment to share how you'd write your unit test!
  • Integration Test
    Jest is one of the most popular test frameworks used in JavaScript.
    Include some code of real examples.
    Reference:
    • https://stripe.com/docs/testing
    • https://javascript.plainenglish.io/mock-stripe-api-in-node-js-with-jest-c9d8df595ff4

End

Summary

• As a best practice in testing, we want to test our code, not necessarily imported code. Ideally, test cases written by the vendor should cover testing for their code. In this case, Stripe as our payment processing platform allows us to rest assured that we only need to test our implementation/integration.

Additional Resources:

• https://programequity.notion.site/Test-Driven-Development-With-Stripe-40de27d593d748e08fdf47296807eab5

Hashtags?

• @StripeDev tweet

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?
  • Someone who may be in similar situation as myself: any developer who is open and eager to learn new technologies, but I'd love to help make the process easier for others.
  • Ideally I'd like to be article to be friendly to those who are new to the SWE journey, but I also like to write concisely, and they can always continue reading the additional resources if there are specific things they don't understand.
• If people could leave with just one action, what would it be?
  • Good question... Go and incorporate this in your current project?
• Were there surprises or alternative problem solving you want to give a heads up to?
  • To be determined? Maybe include versioning for how I am setting things up and remind readers that official docs should be the most up-to-date resource, but hopefully this article helps them to get started

Sample Topics for your blog post

• Creating tests for Stripe

• 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

• Identify your topic from one of the PRs approved I'm still working on the PR
• Outlining bullet points of blog roadmap
• Is your blog a List, Survey, or demo? Demo
• Which Visuals or Diagram or Code snippets will you add? All the above 😉
• References to resources

Draft: How to test a Stripe API (with permissions to comment)

📰 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

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

[unnamedrd]

Hey Joey, which topic did you decide to go with? I believe you've been in the first epic working with Param and Glenn, that might be a better choice for you to write from your own experience. There's not much detail in the second outline (which is fine, especially if you have a clear idea about how to organize the topic), but the question in the topic is clear "How to test a stripe API?".

That's good for two reasons, it clearly defines the problem you're solving for the reader. Also good for discovery because this gets published on a platform like Dev.to and it's likely that a user will type in those search terms. Keep in mind that you'll want to use specific examples from your open source work to demonstrate your point. Additionally remember the word limit (~400-600words) and ensure you can make your case within that limit.