Skip to content

Latest commit

 

History

History
53 lines (31 loc) · 2.84 KB

StyleGuideBlog.md

File metadata and controls

53 lines (31 loc) · 2.84 KB
Raw

Style Guide for Blog Articles

If you're looking for guidance about other types of BSSw contributions, please see https://github.com/betterscientificsoftware/betterscientificsoftware.github.io/blob/master/StyleGuide.md

Publication and Announcements

Blog articles appear here: https://bssw.io/blog_posts and also are announced on the BSSw email digest (monthly).

Length

General guidance is 250-500 words, though this is flexible (some articles have been shorter, some a bit longer).

Source Format

We use Github-Flavored Markdown for blog article markup. However we'll work with you at accept other formats.

A skeleton Markdown template for a blog article, which you can copy and customize is available at https://github.com/betterscientificsoftware/betterscientificsoftware.github.io/blob/master/Articles/Blog/BlogArticleSkeletonA.md

You can provide a pull request for the article in the appropriate directory of the repository: https://github.com/betterscientificsoftware/betterscientificsoftware.github.io/tree/master/Articles/Blog

If you prefer to use another format, you can email the draft to the editor you've been dealing with.

Detailed Formatting Tips

  • The formatting to include a hero image is a bit finicky.
    • The **Hero Image:** tag must be followed by a blank line
    • The image itself must be in a Markdown list item (that is, it starts with -)
  • Positioning of the hero image relative to the contributor and publication date metadata doesn't matter
  • Having a deck and having a hero image in a blog post are mutually exclusive
    • A way to approximate having both is to have the hero image and then put the deck as your first (short) paragraph after the image and italicize it.
  • #### Publication date: is case sensitive (d in particular)

Editorial Process

Once we receive your draft, we'll run it by a professional editor, check that the links and images work as expected, and otherwise prepare it for publication. If your employer requires an internal review and approval process prior to publication, please let us know.

Content

General

Need to say something here

Links, and References

We encourage you to point to a modest numder of additional resources that enhance your article. Too many links tend to distract readers. In most cases, we would like to have the items you refer to in BSSw. These would usually be what we call "curated content", which means short items that provide a pointer to an extenral resource with a short description. You're welcome to prepate those as separate contributions, and we're happy to help.

Images

Need to say something about what kind of images we want to encourage/discourage and point to writeup of how to deal with images in the other repo.