From 8c2f3e94875d6f8c3dc4f1b8cc300f7a6b0518ac Mon Sep 17 00:00:00 2001 From: Wesley Moore Date: Sun, 19 Aug 2018 09:18:42 +1000 Subject: [PATCH] WIP: Writing a Great Rust Blog Post --- .../08/anatomy-of-a-great-rust-blog-post.md | 112 ++++++++++++++++++ .../08/anatomy-of-a-great-rust-blog-post.yaml | 9 ++ 2 files changed, 121 insertions(+) create mode 100644 content/technical/2018/08/anatomy-of-a-great-rust-blog-post.md create mode 100644 content/technical/2018/08/anatomy-of-a-great-rust-blog-post.yaml diff --git a/content/technical/2018/08/anatomy-of-a-great-rust-blog-post.md b/content/technical/2018/08/anatomy-of-a-great-rust-blog-post.md new file mode 100644 index 0000000..58810cb --- /dev/null +++ b/content/technical/2018/08/anatomy-of-a-great-rust-blog-post.md @@ -0,0 +1,112 @@ +To date I've posted 718 posts to [Read Rust]. I can't profess to having read +every single one but I have skimmed them all and have definitely extracted +the information required to post them to the site. Some blogs make this +easier than others. In this post I cover some things you can do to make your +blog and the posts upon it easier for readers and myself alike. + +I'll cover four areas: + +1. Tell a Story +1. Sign Your Work +1. Make It Easy to Read Future Posts +1. Provide Meta Data + +## Tell a Story + +A story has a beginning, middle, and end. Blog posts can benefit from this +structure too. The beginning sets the scene, and provides a shared starting +point for the main content of your post. When a post just dives straight into +the details, without context it can be hard to work out what the topic is, +what background there is, or what the motivations behind the work are. + +Once you've set the scene in your introduction you can dive into the +details knowing your readers are on the same page. This is where the +bulk of your post is written. + +At the end of your post wrap up with a conclusion. This may include a +summary, details of future work, or unsolved problems. + +## Sign Your Work + +Writing a post takes time and effort. You can be proud of that and sign your +work! Be it with your real name, a pseudonym, or handle. When posting to +ReadRust it's important to me to attribute the article to the original author. +I'm aware that some people prefer not to use their real names online and that's +totally ok. When there is no name, a pseudonym, or handle on a blog it is hard +to work out how to credit the author. + +## Make It Easy to Read Future Posts + +So you've written an interesting post that readers have enjoyed, often +they will be interested in reading future posts that you write. You can +make this easy. + +When +looking for posts for Read Rust it would be impractical for me to +manually visit the websites of every interesting blog to see if there +are new posts. That's where [RSS] comes in. RSS lets my subscribe to +your blog in my feed reader of choice and then it will check for new +posts on the sites I follow, allowing me to read them all in one place. + +Pretty much all blogging software supports RSS. If you aren't already +generating a feed I highly recommended adding one. + +If you already have an RSS on your blog ensure it's easily discoverable by +including a link to it on your blog, perhaps in the header, footer, sidebar, or +about page. Additionally include a `` tag on the `` of you HTML to +make the feed automatically discoverable. + +## Provide Meta Data + +There are actually two audiences for your content: humans and machines. +The humans are the readers, the machines are computers such as search +engine indexers, Web Archives, the Read Rust tools! Ideally your content +should be easy for both to read. + +The [add-url tool in the Read Rust codebase][add-url] looks for a number +of pieces of metadata in order to fill in the details that are included +in the entry for every post: + +* **Title** in a `` tag. +* **Author Name** in a `<meta name="author"` tag. +* **Author URL** in a `<link rel="author"` tag. +* **Date Published** in a `<time>` tag, typically nested within an `<article>` tag. +* **Post Summary** (excerpt) in a `<meta name="description"` tag. + +The tool looks for these in the post itself, as well as in the RSS +feed if found. Often it still turns up empty. You can help your +content be more machine readable by including this meta data in your +HTML. The example below shows all of these properties in use. + +```language-html +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8" /> + <meta name="viewport" content="initial-scale=1.0" /> + <title>Post Title + + + + + + + + +
+
+

Post Title

+ + + +
+
+ + + + +``` + + +[add-url]: https://github.com/wezm/read-rust/blob/d41672caaa269fc7f4584e5db2154bd9b3bd3c92/src/bin/add-url.rs +[Read Rust]: https://readrust.net/ diff --git a/content/technical/2018/08/anatomy-of-a-great-rust-blog-post.yaml b/content/technical/2018/08/anatomy-of-a-great-rust-blog-post.yaml new file mode 100644 index 0000000..3837ce3 --- /dev/null +++ b/content/technical/2018/08/anatomy-of-a-great-rust-blog-post.yaml @@ -0,0 +1,9 @@ +--- +title: Writing a Great Rust Blog Post +extra: Some tips for writing a blog post that is readable by humans and machines alike. +kind: article +section: technical +created_at: 2018-08-18 16:17:00.000000000 +10:00 +keywords: +- rust +short_url: