benw2/wezm.net
1
0
Fork 0
forked from wezm/wezm.net
Code Pull requests Activity

Finish anatomy-of-a-great-rust-blog-post

Browse source
This commit is contained in:
Wesley Moore 2018-08-19 14:39:28 +10:00
parent 8c2f3e9487
commit 2764237730
No known key found for this signature in database
GPG key ID: BF67766C0BC2D0EE
11 changed files with 71 additions and 76 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.ruby-version
View file

@ -1 +1 @@
2.4.1
2.5.1

5
Gemfile.lock
View file

@ -93,6 +93,8 @@ GEM
rb-fsevent (0.10.3)
rb-inotify (0.9.10)
ffi (>= 0.5.0, < 2)
rb-kqueue (0.2.5)
ffi (>= 0.5.0)
rdiscount (2.2.0.1)
ref (2.0.0)
rouge (3.2.1)
@ -126,6 +128,7 @@ DEPENDENCIES
nanoc (~> 4.0)
nokogiri
rake
rb-kqueue (>= 0.2)
rdiscount
rouge
rubypants
@ -133,4 +136,4 @@ DEPENDENCIES
systemu
BUNDLED WITH
1.16.0
1.16.3

27
TODO
View file

@ -1,27 +0,0 @@
Now
---
* Setup monothumb on server
* Exclude photo and photos.xml from deploy:rsync
Deployment
----------
* Move Wordpress to old. and add robots.txt
Later
-----
* Add monothumb to GitHub
* Revise About page content
* Get proper lens specs for About page
* Fully convert to HTML5
* Microdata on About/Contact pages
* Add favicon
* Add weights to sitemap
Future
------
* Make it possible to purchase the HTML
* Make a Wordpress theme out of the site

4
content/screen.sass
View file

@ -435,6 +435,10 @@ table
.text-right
text-align: right
.heading-icon
height: 20px
margin-right: 0.25em
// Weather
body.weather

99
content/technical/2018/08/anatomy-of-a-great-rust-blog-post.md
View file

@ -1,81 +1,79 @@
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.
every single one completely (although I have read a lot of them) but I have at
least skimmed them all and 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, to read and share with as many people as possible.
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
1. Provide Metadata
## Tell a Story
<h2><img src="/images/2018/noun_Book_1561008.svg" class="heading-icon" alt ="" /> Tell a Story</h2>
A story has a beginning, middle, and end. Blog posts can benefit from this
A story has a beginning, middle, and end. Blog posts 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.
the details without context it can be hard to follow the topic,
the background, and the motivations behind the work.
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.
Once you've set the scene in your introduction, you can dig into the details
knowing your readers are on the same page, and more likely to follow along. 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
<h2><img src="/images/2018/noun_write_1560855.svg" class="heading-icon" alt ="" /> Sign Your Work</h2>
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.
work! I'm aware that some people prefer not to use their real names online. A
pseudonym, or handle, work well too. When posting to Read Rust it's important to
me to attribute the article to the original author. When there is no
information on a post it's hard to work out how to credit the post.
## Make It Easy to Read Future Posts
<h2><img src="/images/2018/noun_Transmitter_1560979.svg" class="heading-icon" alt ="" /> Make It Easy to Read Future Posts</h2>
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
If you've written an interesting post that readers have enjoyed, often they
will want to read future posts that you write. You can make this easy using an
RSS feed. 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.
If you already have an RSS feed on your blog ensure it's easily discoverable by
linking it. Perhaps in the header, footer, sidebar, or about page. Additionally
include a `<link rel="alternate">` tag in the `<head>` of your HTML to make the
feed automatically discoverable by feed readers. MDN have a great tutorial series
about RSS covering these details: [Syndicating content with RSS][rss].
## Provide Meta Data
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.
RSS lets me subscribe to blogs in my feed reader of choice ([Feedbin]),
allowing me and other readers to discover, and read your new posts all in one
place.
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.
<h2><img src="/images/2018/noun_Tag_1560911.svg" class="heading-icon" alt ="" /> Provide Metadata</h2>
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][ddg], [web archivers][archive], and 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.
* **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.
* **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
content be more machine readable by including this metadata in your
HTML. The example below shows all of these properties in use.
```language-html
@ -107,6 +105,19 @@ HTML. The example below shows all of these properties in use.
</html>
```
So that's it. Four things you can do to help make your blog more readable,
attributable, and discoverable. Your readers, human and machine will thank you.
With thanks to Gregor Cresnar from the Noun Project for the icons used in this post:
* [Book](https://thenounproject.com/search/?q=book&collection=46510&i=1561008#)
* [Tag](https://thenounproject.com/search/?q=tag&collection=46510&i=1560911#)
* [Transmitter](https://thenounproject.com/search/?q=signal&collection=46510&i=1560979#)
* [Write](https://thenounproject.com/search/?q=write&collection=46510&i=1560855#)
[Feedbin]: http://feedbin.com/
[add-url]: https://github.com/wezm/read-rust/blob/d41672caaa269fc7f4584e5db2154bd9b3bd3c92/src/bin/add-url.rs
[Read Rust]: https://readrust.net/
[ddg]: https://duckduckgo.com/
[archive]: https://web.archive.org/
[rss]: https://developer.mozilla.org/en-US/docs/Web/RSS/Getting_Started

4
content/technical/2018/08/anatomy-of-a-great-rust-blog-post.yaml
View file

@ -1,6 +1,6 @@
---
title: Writing a Great Rust Blog Post
extra: Some tips for writing a blog post that is readable by humans and machines alike.
title: Anatomy a Great Rust Blog
extra: I've posted 718 articles to Read Rust. This post shares some insights I've gleaned from them, to make your posts as readable and discoverable as possible.
kind: article
section: technical
created_at: 2018-08-18 16:17:00.000000000 +10:00

2
layouts/article.html
View file

@ -13,7 +13,7 @@
<img src="/images/comment.svg" width="32" height="32" alt="Comment icon" class="comment align-top" />
Stay in touch!
</h2>
<p>Follow me on <a href="https://twitter.com/wezm">Twitter</a>, or <a href="https://mastodon.social/@wezm">Mastodon</a>, <a href="/feed/">subscribe to the feed</a>, or <a href="mailto:wes@wezm.net">send me an email</a>.
<p>Follow me on <a href="https://twitter.com/wezm">Twitter</a> or <a href="https://mastodon.social/@wezm">Mastodon</a>, <a href="/feed/">subscribe to the feed</a>, or <a href="mailto:wes@wezm.net">send me an email</a>.
</p>
</div>
</article>

1
output/images/2018/noun_Book_1561008.svg Normal file
View file

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" data-name="Layer 1" viewBox="0 0 100 100" x="0px" y="0px"><path d="M10,18V82a5,5,0,0,0,.13.67c0,.44-.13.87-.13,1.33A14,14,0,0,0,24,98H86a4,4,0,0,0,4-4V6a4,4,0,0,0-4-4H26A16,16,0,0,0,10,18ZM82,90H24a6,6,0,0,1,0-12H82Zm0-20H24a13.89,13.89,0,0,0-6,1.4V18a8,8,0,0,1,8-8H82Z"/><path d="M34,46H66a4,4,0,0,0,4-4V26a4,4,0,0,0-4-4H34a4,4,0,0,0-4,4V42A4,4,0,0,0,34,46Zm4-16H62v8H38Z"/></svg>
Side by side

After

Width:  |  Height:  |  Size: 422 B

1
output/images/2018/noun_Tag_1560911.svg Normal file
View file

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" x="0px" y="0px" viewBox="0 0 100 100" style="enable-background:new 0 0 100 100;" xml:space="preserve"><path d="M86,2H53.2C50,2,47,3.2,44.8,5.6L6.2,44c-5.4,5.4-5.4,14.4,0,19.8l0,0l29.8,30c5.4,5.4,14.4,5.4,19.8,0l0,0l38.6-38.6 C96.6,53,98,50,98,46.8V14C98,7.4,92.6,2,86,2z M90,46.6c0,1-0.4,2-1.2,2.8L50.2,88.2c-2.4,2.4-6.2,2.4-8.4,0l-30-29.8 c-2.4-2.4-2.4-6.2,0-8.4l38.6-38.6c0.8-0.8,1.8-1.2,2.8-1.2H86c2.2,0,4,1.8,4,4V46.6z"/><path d="M72,22c-3.4,0-6,2.6-6,6s2.6,6,6,6s6-2.6,6-6S75.4,22,72,22z"/></svg>
Side by side

After

Width:  |  Height:  |  Size: 601 B

1
output/images/2018/noun_Transmitter_1560979.svg Normal file
View file

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" data-name="Layer 1" viewBox="0 0 100 100" x="0px" y="0px"><path d="M16.06,16.05C-2.82,34.93-3.23,66.42,15.17,84.82a4,4,0,1,0,5.66-5.66C5.5,63.83,5.9,37.52,21.71,21.7a40.07,40.07,0,0,1,56.58,0c15.81,15.82,16.21,42.13.88,57.46a4,4,0,0,0,5.66,5.66c18.4-18.4,18-49.89-.89-68.77A48,48,0,0,0,16.06,16.05Z"/><path d="M72.83,72.82A31.61,31.61,0,0,0,82.1,50.06a32.21,32.21,0,0,0-9.47-22.7,32,32,0,0,0-45.26,0,32.21,32.21,0,0,0-9.47,22.7,31.61,31.61,0,0,0,9.27,22.76,4,4,0,0,0,5.66-5.66,23.62,23.62,0,0,1-6.93-17A24.24,24.24,0,0,1,33,33,24,24,0,0,1,67,33a24.24,24.24,0,0,1,7.13,17.1,23.62,23.62,0,0,1-6.93,17,4,4,0,0,0,5.66,5.66Z"/><path d="M34,90a4,4,0,0,0,0,8H66a4,4,0,0,0,0-8H54V65.42a15.94,15.94,0,0,0,7.31-26.74,16.36,16.36,0,0,0-22.62,0A15.91,15.91,0,0,0,46,65.42V90Zm8-40a8,8,0,1,1,13.66,5.66,8.2,8.2,0,0,1-11.32,0A8,8,0,0,1,42,50Z"/></svg>
Side by side

After

Width:  |  Height:  |  Size: 878 B

1
output/images/2018/noun_write_1560855.svg Normal file
View file

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" data-name="Layer 1" viewBox="0 0 100 100" x="0px" y="0px"><path d="M14,98H74A12,12,0,0,0,86,86V74a4,4,0,0,0-8,0V86a4,4,0,0,1-4,4H14a4,4,0,0,1-4-4V26a4,4,0,0,1,4-4H26a4,4,0,0,0,0-8H14A12,12,0,0,0,2,26V86A12,12,0,0,0,14,98Z"/><path d="M98,6a4,4,0,0,0-4-4H86A56.06,56.06,0,0,0,30,58v6.34L19.17,75.17a4,4,0,0,0,5.66,5.66L35.66,70H42A56,56,0,0,0,83.85,51.13a4,4,0,0,0,.21-5.06l-5.88-8a.14.14,0,0,1,.15-.09H90a4,4,0,0,0,3.69-2.46A55.63,55.63,0,0,0,98,14Zm-8,8a47.71,47.71,0,0,1-2.74,16H78.33A8.17,8.17,0,0,0,71.8,43.07l3.83,5.1A48,48,0,0,1,42,62H38V58A48.05,48.05,0,0,1,86,10h4Z"/></svg>
Side by side

After

Width:  |  Height:  |  Size: 622 B