Skip to content

Latest commit

 

History

History
105 lines (77 loc) · 7.85 KB

writers-guide.md

File metadata and controls

105 lines (77 loc) · 7.85 KB
Raw

Serverless writer’s guide

We are an open source company to our core, and we love community contributions to the Serverless Blog, the most popular serverless-focused publication on the web. Do you have something neat to say about serverless technologies? Awesome.

Read our Serverless Writer’s Guide below to learn about our publication requirements. The suggested topics and our style guide are mandatory reading before submitting to our blog.

Plus, we've included outlines, example posts, helpful links & more! If you have suggestions about how to make this guide better, let us know.

Content guidelines

  • Focus on results and learnings. Tell readers how you did something great with serverless, and what you learned along the way.
  • Provide code examples or tutorials when possible. Our audience wants to be hands-on.
  • No overt product pitches. These aren’t received well by our audience, and will not be published on our blog.

Style guide

  • Do not use title case in your title. Capitalize the first word and proper nouns only. This goes for section headers, too.
  • Use h4 for section headers, and h5 for subsection headers. Aka, h2 = h4, h3 = h5. We do not have an h4 equivalent, and you should never use h1.
  • Include a header image that is 1200 x 600 px.
  • Never put anything in a quote to emphasize it, or to note an edge case, etc. Instead, write Note: and put your note there.
  • Use clear, concise language and short sentences. When in doubt, use shorter paragraphs and shorter sentences. If you have a sentence that runs three lines long, then try to break it up. This makes blog posts much easier to read on mobile.
  • Use a conversational tone that’s familiar, but not informal. Here’s a great example.
  • Use contractions (i.e., 'we’re' vs. 'we are').
  • Only 1 space after a period or colon.
  • Capitalize the first letter in every sentence.

Suggested topics

  • How I built X with serverless
  • How I saved $X with serverless
  • How to use X serverless plug-in or component
  • How to use this popular development framework with serverless
  • Learnings from doing X with serverless (security, migrations, authentication, etc)
  • Use cases with serverless/FaaS technologies and microservices
  • Serverless Framework how-to posts or tutorials
  • Serverless observability how-to posts or tutorials
  • Answers to forum questions (if it's a popular forum post, people would probably love to see a long-form answer!)
  • Deep dive into new features, either with the Serverless Framework, or something relevant to Framework developers
  • We are especially keen right now on publishing things relating to Golang, GCF, Azure, Cloudflare, and Node8
  • AWS + Lambda tutorials also do well!
  • General developer tips & tricks

Example posts

Check out the following examples for writing inspiration:

Choosing a topic

The Serverless team can find a list of ideas along with a schedule in the Content Calendar in Asana. The Serverless team gets first dibs on selecting topics, then we turn to guest authors. Posts are scheduled 1-6 weeks in advance.

Creating an outline

It’s helpful to organize your ideas in an outline before you start writing. Your outline will depend on the type of post you’re writing, but here are a few prompts to get you started.

Note: These are just suggestions. Feel free to change things up to fit your needs.

Generic outline -> full post process

  • Write down the one thing you want people to take away from this post in no more than 1-2 sentences. Be clear and concise. This is your chance to convince the reader that it’s worth their time to keep going.
  • Think about all the steps involved in achieving the goal. Write those down. Those are your section headers.
  • If any of your steps are particularly beefy, write the steps involved in achieving those. Those are your subsection headers.
  • Under each section and subsection, write a single-word bulleted list of the things you will cover.
  • Turn those single words into entire sentences.
  • Turn those single sentences into multiple sentences where necessary.
  • Add a 'Conclusion' or 'Wrap-up' section at the end. Tie everything together by recapping what you’ve talked about and sharing any relevant next steps. This would also be a great place to include any additional related resources you’d like to share.

Writing about a project

  • What problem did you set out to solve with your project?
  • What was the benefit of using serverless architecture?
  • Walk us through your process and architecture, including code.
  • Share any relevant lessons learned.
  • Share your vision for the future of your project/next steps.
  • Feel free to include anything else you think is useful/relevant for the post.

How-to post

  • Break your process down into individual steps that are clearly labeled. Each step should be one complete thought or action. Include relevant screenshots or code snippets as needed.
  • Recap your process and include any relevant next steps or additional resources.

Posting on GitHub

You can post your draft to the Serverless blog repo for editing and review.

Please add your author file along with your post. This will include links to your GitHub, Twitter, personal or company website, in addition to a short and long bio. Your photo will be your GitHub avatar

Writing resources

Check out these additional resources for more tips and tools to help you produce great content: