search

OpenSourceFellows / open-source-mentorship

Inspiring the next generation of open source contributors and maintainers
https://www.notion.so/programequity/ProgramEquity-Open-Source-Fellows-5f4dfc06109842779b81e8166c056334
Creative Commons Zero v1.0 Universal
13 stars 0 forks source link

✍️ @_joey_ma's Blog #30

Open joey-ma opened 1 year ago

joey-ma commented 1 year ago

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:

Timeline:

📋 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:

Middle

Helpful examples/concepts:

End

Summary:

Additional Resources:

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:

Middle

End

Summary

Additional Resources:

Hashtags?

Requirements

Questions to consider:

Sample Topics for your blog post

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

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

unnamedrd commented 1 year ago

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.