Merge pull request #26 from melissamahoney-mongodb/DOCSP-6823

(DOCSP-6823): Update & republish Blogs Guidelines page

Author: melissamahoney-mongodb

source/style-guide/blog-guidelines.txt

@@ -1,209 +1,78 @@
 .. _blog-guidelines:
 
 ===============
-Blog guidelines
+Blog Guidelines
 ===============
 
-Developers often ask an Technical Writer to edit a blog that they
-have written and placed in the
-https://github.com/rackerlabs/docs-developer-blog repository. Blogs in
-this repository are published to the MongoDB Developer Blog site at
-https://developer.MongoDB.com/blog/.
+When you write a blog post, your grammar should be correct but you do
+not have to adhere strictly to the technical documentation Style Guide.
+The following guidelines are specific to writing blog posts for the
+`MongoDB Blog <https://www.mongodb.com/blog>`__.
 
-When you write a blog, use the writing guidelines in this Style Guide
-as you would with other documentation that is curated by the
-Documentation team. Start with the information in the
-:ref:`quickstart`.
-
-This topic provides additional guidelines specific to writing blogs for
-the MongoDB Developer Blog site.
-
-
-Things to consider before writing a blog
-----------------------------------------
-
-Before you start writing, consider the following questions:
-
-- What is the goal of this developer blog? Describe it in two sentences
-  or less.
-
-  - Is it to be helpful and answer a question or offer how-to
-    information?
-  - Is it to provide “thought leadership” or show our expertise in an
-    area? If so, describe what you’d like to convey.
-  - Is it something else altogether? If so, what? It’s possible that
-    your idea might be better presented as an article on the How-To
-    support site at https://support.MongoDB.com/ or as a blog with a
-    marketing flavor published at https://blog.MongoDB.com/.
-
-- What is the significance of the content of the blog? Is it how to use
-  a new offering? How is it helpful to customers? Does it frame our
-  expertise is a new way?
-- Explain how the content of the blog aligns with, supports, or
-  strengthens MongoDB’s current business priorities and strategy.
-- Who is the target audience for this blog?
-- What specific customer problems or pain points does the blog address?
-  Provide names of customers willing to be references in support of the post.
-- Does the blog describe how to use something that MongoDB provides
-  that it does better than the competition or that no other competitor
-  offers? Does the blog provide quantifiable and defensible information
-  (such as performance metrics) showing the MongoDB edge over the
-  competition? If yes, explain.
-
-
-Blog writing suggestions
-------------------------
-
-When you write your content, we recommend the following rules of thumb:
-
--  Length: MongoDB blog posts generally run between 500-1,000 words,
-   but let the content be your guide. Take the space you need to tell
-   your story, but don’t pad it unnecessarily. Going long is okay, too,
-   as long as it’s worth reading.
-
--  Tools: Use the word processor or text editor of your choice to write
-   the blog.
-
--  General format:
-
-   - An attention-grabbing opening, known in the news business as a
-     “lede”
-
-   - A “nut graf” - a sentence or two letting readers know what you’re
-     going to be talking about and why it matters
-
-   - Some background information or context, such as the history of a
-     product
-
-   - A conclusion (and a call to action, if appropriate) with links and
-     contact information
-
-- Consistency: Be as consistent as possible in style with other blogs
-  on the MongoDB Developer Blog site.
-
-- Bullet points: Bullet points are useful for listing features.
-
-- Images:
-
-  - Images should directly support or illustrate blog content. Examples
-    include a screen shot, diagram, or table that illustrates the
-    concept or technique that is being described.
-  - Any image pulled from another source should provide a reference to
-    the source directly underneath the image.
-  - Add social media icons with their links for twitter, Facebook, and
-    LinkedIn at the bottom of the blog post. (Information Development
-    provides a template for this that you can add to your blog.)
-
-- Reference section: If your content uses a lot of content from another
-  source, provide a Reference section at the bottom of the blog post
-  with a link to the reference.
+Blog Manifesto
+--------------
 
-- Think “be helpful” rather than trying to sell a product or service.
-  *What* does the product do? *How* does it help the customer?
+For the goodness of the reader through the betterment of the company:
+the core principles for communicating through the blog will be...
 
-- Write a good lede: When crafting your lede, consider how the
-  information in your post helps customers. An announcement of a new
-  product is not a lede, but that product’s money-saving capacity may
-  well be one. For example:
+Style: Personal, Professional, Conversational
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-  Not good: Today MongoDB is pleased to announce the release of four
-  new features in Office 365.
+- Always address the reader personally
 
-  Good: Increased storage, security, and cost-saving measures are now
-  available to enhance the already-robust Office 365 suite available
-  from MongoDB, making it even more attractive to a wider variety of
-  business users.
+  - Because you are looking to engage them
 
-- Stay focused on your topic: If you find yourself straying, you may
-  have enough material for a series. It’s okay to break up a big topic
-  into more digestible bites. Formulas like How to, Top 5 or 10, and
-  curated lists tend to do well.
+  - But never try to be a buddy
 
-- Show don’t tell. Can you create a graphic or image, or add a screen
-  shot to illustrate your point?
+- Always address the reader professionally
 
-- Avoid jargon. Rackers (and the entire tech industry) tend to speak in
-  jargon. Unless your post is aimed at a technical audience, use plain
-  English. There is never a reason to use business jargon.
+  - Because you want to establish your credentials as a peer
 
-- Link link link: A first product mention? Link to the product page.
-  Outside accolades? Link to it. Citing a study or source or article?
-  Link to it. Have we written about it before? Link to it. Mention a
-  partner or customer? Link to their site.
+  - Avoid appeals to authority unless you are the authority
 
-- Keep it concise: The Internet has shrunken everyone’s attention span.
-  Say it once, say it well. No need to repeat the same information in
-  different format. Similarly, keep paragraphs short. Long blocks of
-  text are intimidating. Use concrete examples whenever possible. If
-  you get stuck, don’t fret. Just send your draft to the blog team.
-  We’re here to help.
+- Always address the reader conversationally
 
+  - Because this is a blog, not a formal news release (usually)
 
-Voice and tone
---------------
+  - But avoid writing a conversation
 
-Use these guidelines to write a blog that is friendly, helpful, and
-inspires confidence.
+Form: Narrative, Focus, Enjoy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The primary job of the words in a blog is to help users complete tasks
-with no confusion and minimal interruption. However, the voice and tone
-that we use with words also influence how people think and feel about
-MongoDB.
+- Always try to talk narratively
 
-Voice is our style, and communicates our personality to the user. Tone
-is our mood, and communicates our attitude about the subject to the
-user.
+  - Because narrative style guides the reader’s attention
 
-The words we choose, and the ways we use them, should reflect our
-goals: building trust, inspiring confidence, making things easier, and
-developing a relationship with MongoDB users.
+  - But, treat the opener as a TL;DR - don’t tease.
 
-When you write blog text, use words that reflect the following
-attributes:
+- Focus on communicating one core thing
 
-- Human
-- Trustworthy
-- Knowledgeable
-- Accurate
-- Professional
-- Approachable
-- Helpful
+  - Because there is always another blog article for other things
 
-Consider the following best practices for voice and tone when you write
-blog text:
+  - Don’t waste the reader’s attention
 
-- Write in a way that the user wants to be spoken to. Use helpful words
-  and phrases that are informative, simple, clear, and easy to
-  understand.
+- Write so you are enjoying writing
 
-- Temper the enthusiasm conveyed in confirmation messages.
+  - Because words written honestly communicate your feelings
 
-- Be careful about laying blame. Don’t take the blame for a negative
-  situation. Don’t lay the blame of the negative situation on the user.
+Approach: Topicality, Solutions, Inspiration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- In positive situations, be encouraging and offer next steps. Don’t
-  take credit for the user’s success.
+- Look for a topical approach to frame your writing
 
-- In negative situations, be clear about the problem and how the user
-  can fix it. Don’t ask the user to trust us without providing more
-  information.
+  - Find a current trend, report, article to ride on because currency
+    counts
 
+  - But avoid memes and fads, they age stories in days.
 
+- Look to solve a problem for the reader
 
-Write to the user by using second person and imperative mood
-------------------------------------------------------------
+  - Even if its one they don’t have yet.
 
-Users are more engaged with content when it talks to them directly. You
-talk to users directly by using *second person*, addressing the user as
-*you*. Second person also promotes a friendly tone. For more
-information, see :ref:`write-to-the-user`.
+  - But don’t make it sound like they created the problem
 
-The following guidelines for writing to the user apply specifically to
-the MongoDB developer blogs:
+- Aim to give at least some of the readers an “Aha!” moment
 
--  For blogs, use the first-person singular pronoun *I* only when
-   authors of blogs are describing their own actions or opinions.
+  - Because that’s the greatest gift you can give to a reader
 
--  Switching person (point of view) is acceptable in blog posts that
-   use first-person singular but then switch to second person for
-   instructional steps.
+  - And remember some “Aha!” moments may appear mundane