From 2764237730079cca0cf561aea4a8754eeb0d963a Mon Sep 17 00:00:00 2001 From: Wesley Moore Date: Sun, 19 Aug 2018 14:39:28 +1000 Subject: [PATCH] Finish anatomy-of-a-great-rust-blog-post --- .ruby-version | 2 +- Gemfile.lock | 5 +- TODO | 27 ----- content/screen.sass | 4 + .../08/anatomy-of-a-great-rust-blog-post.md | 99 ++++++++++--------- .../08/anatomy-of-a-great-rust-blog-post.yaml | 4 +- layouts/article.html | 2 +- output/images/2018/noun_Book_1561008.svg | 1 + output/images/2018/noun_Tag_1560911.svg | 1 + .../images/2018/noun_Transmitter_1560979.svg | 1 + output/images/2018/noun_write_1560855.svg | 1 + 11 files changed, 71 insertions(+), 76 deletions(-) delete mode 100644 TODO create mode 100644 output/images/2018/noun_Book_1561008.svg create mode 100644 output/images/2018/noun_Tag_1560911.svg create mode 100644 output/images/2018/noun_Transmitter_1560979.svg create mode 100644 output/images/2018/noun_write_1560855.svg diff --git a/.ruby-version b/.ruby-version index 005119b..73462a5 100644 --- a/.ruby-version +++ b/.ruby-version @@ -1 +1 @@ -2.4.1 +2.5.1 diff --git a/Gemfile.lock b/Gemfile.lock index d0d67cb..fcd43b2 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -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 diff --git a/TODO b/TODO deleted file mode 100644 index 0b513b4..0000000 --- a/TODO +++ /dev/null @@ -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 diff --git a/content/screen.sass b/content/screen.sass index fe2fd2d..7139a26 100644 --- a/content/screen.sass +++ b/content/screen.sass @@ -435,6 +435,10 @@ table .text-right text-align: right +.heading-icon + height: 20px + margin-right: 0.25em + // Weather body.weather 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 index 58810cb..3e2d767 100644 --- 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 @@ -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 +

Tell a Story

-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 +

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. +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 +

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 +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 `` tag on the `` 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 `` tag in the `` 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. +

Provide Metadata

+ +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 `` 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 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 index 3837ce3..e20a3f5 100644 --- 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 @@ -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 diff --git a/layouts/article.html b/layouts/article.html index ec02789..c7081e6 100644 --- a/layouts/article.html +++ b/layouts/article.html @@ -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> diff --git a/output/images/2018/noun_Book_1561008.svg b/output/images/2018/noun_Book_1561008.svg new file mode 100644 index 0000000..5512a98 --- /dev/null +++ b/output/images/2018/noun_Book_1561008.svg @@ -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> diff --git a/output/images/2018/noun_Tag_1560911.svg b/output/images/2018/noun_Tag_1560911.svg new file mode 100644 index 0000000..784bd06 --- /dev/null +++ b/output/images/2018/noun_Tag_1560911.svg @@ -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> diff --git a/output/images/2018/noun_Transmitter_1560979.svg b/output/images/2018/noun_Transmitter_1560979.svg new file mode 100644 index 0000000..3df5732 --- /dev/null +++ b/output/images/2018/noun_Transmitter_1560979.svg @@ -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> diff --git a/output/images/2018/noun_write_1560855.svg b/output/images/2018/noun_write_1560855.svg new file mode 100644 index 0000000..b50838b --- /dev/null +++ b/output/images/2018/noun_write_1560855.svg @@ -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>