Communications Guide#

Blog#

We publish our blog at https://blog.jupyter.org. We welcome ideas for posts or guest posts to the Jupyter blog. If you have a suggestion for a future post, please feel free to share your idea with us. We would like to discuss the idea with you.

Do you enjoy writing? Please contact us about becoming a guest blogger. We can help guide you through the process of creating a post.

Technical overview#

Jupyter’s blog uses the Ghost blog platform for its contributor flexibility and ease of use. Jupyter’s blog is deployed at https://blog.jupyter.org.

Basic workflow from blog idea to published post#

There are several major steps in the workflow from blog idea to a published post including:

  • Be inspired to write a post

  • Send us a message on the Jupyter mailing list and ask us for an author account on our blog

  • Creating a draft

  • Draft Review

  • Editorial acceptance

  • Publishing the post

We’ll cover each of these as well as how to update a post once it has been published.

Creating a draft#

Title and metadata#

Always check in the metadata fields that a blog post has a title and a canonical URL. It is possible to put the date in the canonical URL, in particular for events like jupyter-day, that can occur several times. The date of the event can differ from the date of the blog post.

Once a post is published, never change the post’s title or the url. These changes will break links of tweets and RSS feeds that have already referenced the existing, published URL. Keep in mind that when publishing some platforms cache the url immediately; as a result changing the title will direct people to a 404 page.

Title and metadata can always be refined after the actual content of the blog is written, but should not be changed after publication. As a guest you do not have to worry about metadata, the editor or admins will take care of that.

Working with images#

Try not to link to external images. If you want to put an image in the post, insert ![]() in the editor view and drag and drop an image from your desktop into the newly created field in the preview. External images can change, and can break the blog post if they are taken down. This cannot append if you drag and drop images. Moreover, these images will be served from the same CDN (Content Delivery Network) as the blog, which will insure the best overall experience for our readers.

The featured image you see at the top of a blog posts is set from within the metadata field, not using the ![](). The featured image is treated differently than inlined images by many feedreaders (especially on mobile) and allows a user on a slow connection to read the content of the blog earlier, which is a much better experience for the user than waiting for the featured image to render.

Draft review#

Ask for a review#

Once you think you are done, ask someone else to reread your post, and check the various parameters that you might have forgotten before publishing. You are not on your own, this is teamwork, we are here to help you. If we do things in a hurry you will probably spend more time fixing mistakes that actually doing things right in a first place.

Editorial acceptance#

Publishing the post#

Usually an editor or admin will take care of publishing the post. The task of the Editor/Admin is to check all metadata are correctly set, that no external images are used, as well as all other quality check describe before.

It is then just a matter of making th post visible to everyone.

Changing an existing post#

Posts Updates#

Blog subscribers may receive notification at every update. So use updates and fixes parsimoniously. It is OK to wait a few hours to fix a typo.

If some substantial updates have to be made, like change of location, time etc, please insert an [Update] section at top (or bottom of the blog post depending on importance) with the Date/Time of the update. If the information in the body of the blog is wrong, try not to replace it, and just use strike-through to mark it as obsolete. This would help reader determine which information is correct when dealing with multiple source giving different information.

Newsletter#

Documentation in progress.

Website#

Documentation in progress.