forked from wezm/wezm.net
WIP: Writing a Great Rust Blog Post
This commit is contained in:
parent
0dcb34a4d6
commit
8c2f3e9487
2 changed files with 121 additions and 0 deletions
112
content/technical/2018/08/anatomy-of-a-great-rust-blog-post.md
Normal file
112
content/technical/2018/08/anatomy-of-a-great-rust-blog-post.md
Normal file
|
@ -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 `<link>` tag on the `<head>` 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 `<title>` 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</title>
|
||||||
|
<meta name="description" content="The design and operation of the little Rust content aggregator I built.">
|
||||||
|
<meta name="author" content="Wesley Moore">
|
||||||
|
<link rel="alternate" href="http://www.wezm.net/feed/" type="application/atom+xml" title="WezM.net - All Articles" />
|
||||||
|
<link rel="author" href="http://www.wezm.net/" />
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<!-- header, nav, etc. -->
|
||||||
|
|
||||||
|
<main>
|
||||||
|
<article>
|
||||||
|
<h1>Post Title</h1>
|
||||||
|
<time datetime="2018-06-03T07:34">03 June 2018</time>
|
||||||
|
|
||||||
|
<!-- post content -->
|
||||||
|
</article>
|
||||||
|
</main>
|
||||||
|
|
||||||
|
<!-- footer, etc. -->
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
[add-url]: https://github.com/wezm/read-rust/blob/d41672caaa269fc7f4584e5db2154bd9b3bd3c92/src/bin/add-url.rs
|
||||||
|
[Read Rust]: https://readrust.net/
|
|
@ -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:
|
Loading…
Reference in a new issue