Tuesday, October 17, 2017
Having a blog most often means you’re going to be dealing with a content management system like Wordpress.
While powerful, Wordpress has some familiar drawbacks. For one, backing up Wordpress is a pain and the security updates are almost constant. The WSYWIG editors also make it difficult to see what HTML is being produced and you can end up with inflated, unnecessary code. Plus, what happens if you don’t need a full-blown CMS?
This is where Jekyll comes in.
Jekyll describes itself as a “simple, blog-aware, static site generator”. What that means is that Jekyll allows you to transform your plain text into a blog or a static website by taking a template directory with raw text files and running it through a converter, which then produces a ready-to-publish blog or static website page that will work with whatever web server you choose. “Blog-aware” really just means that it can be used to create a blog, of any other kind of website that follows a series of posted entries.
While there are a couple methods to getting going with Jekyll, forking a starting point is the easiest way to get you up and running in just a few minutes. Forking a repository that follows best practices allows you to skip reading a ton of documentation. The options are pretty endless, but "Jekyll Now" and "poole" both give solid results.
What starting with the fork will allow you to do is get a feel for Jekyll without setting up a local dev environment, install dependencies and work out the build process. Instead, let GitHub pages build the website for you until you need to build it locally.
As a GitHub user, you’re entitled to one free “user” website. This website will live at http://yourusername.github.io, which is a perfect place for your Jekyll blog. GitHub will also provide free hosting for Jekyll blogs, which can save you $50+ a year. A nice bonus, if we’ve ever heard of one.
By placing your unbuilt Jekyll on the master branch of your user repository,
GitHub will automatically build the static website and serve it, without you having to worry about the build process.
Once this happens, click on the “settings” button in your brand new, forked repository, and replace yourusername with your GitHub name. From here, the website will go live immediately.
That fast? Yep.
From here, the customization begins. You can change the site’s name, description and more by editing the "_config.yml" file. These are custom variables that are there for your convenience and get pulled into the theme when your site is built. Making any changes to your "_config.yml" file will make GitHub Pages rebuild your site with Jekyll.
You can alter the site’s files in 3 ways:
Continue reading on Linkedin.
Posted by Richard at 10:24 AM
Thursday, March 30, 2017
Posted by Richard at 7:55 AM
Wednesday, November 9, 2016
We've all heard it said that you should know your audience. But, how many of us actually consider this? I am here to tell you that this is THE MOST IMPORTANT aspect of technical writing, or any writing for that matter. If you are writing an email, if you are writing a user guide, if you are writing a quick-start guide, if you are writing Facebook content, it all starts with knowing who your audience is. That is the foundation of your writing and we all know what happens when you build on a bad foundation - (continue reading on linkedin)
Posted by Richard at 2:51 PM
Monday, October 31, 2016
We've all heard it for years. Everything uses XML for something or other. Computer programs use it; help authoring tools use it; even web pages use it. XML stands for extensible markup language. HTML, or hypertext markup language, is a version of XML used to render web pages in browsers. Put another way, a web browser is a piece of software written to parse XML files in order to render the results in a human-readable form. But, what is the big deal with XML?
Continue reading on Linkedin.
Posted by Richard at 5:26 PM
Wednesday, September 28, 2016
We humans have this incredible ability to enter a certain mental space, the zone if you will, when we are heavily involved in problem solving of creativity. I first noticed it when I was 14 years old. I had learned BASIC programming on the Sinclair ZX-81 computer. It had a 8-bit Z-80 microprocessor running at 3.25 MHz, and only 1 KB of RAM. Let's just say that it wasn't very fast at all.
I was trying to make a Space Invaders-style game and found that the interpreted BASIC language was just too slow. I decided to make the game using Assembly. At 14, that was a monumental undertaking. After a few months, ....
to see more, read the article on linkedin.
Posted by Richard at 7:43 PM
Thursday, September 22, 2016
After my last article on tools, I found myself wanting to go more in depth with Asciidocs and compare it to a typical Help Authoring Tool (HAT) or WYSIWYG, such as Microsoft Word. I will go over some of the features and benefits of Asciidocs over other writing systems.
- Ease of Use Makes it Quicker
- Works on Any OS
- Infinite Table of Contents
- Content Reuse
- Multiple Outputs
Posted by Richard at 10:16 AM