Contributing to Our Website

Purpose

One of the best ways to contribute to Innolitics outside of client work—writing articles, improving our training program, or polishing our handbook—is to update our website. This lesson will introduce you to Jekyll, the static site generator that produces our website, and show you how you can contribute to website updates.

Learning Material

Read through the website’s README.

Read through our article writing process.

Skim through the Jekyll documentation. The pages within the “CONTENT” and “SITE STRUCTURE” sections are especially relevant.

Keeping your understanding of Jekyll in mind, skim through our website’s source code.

Exercises

To learn as much as possible from these exercises, write your responses before revealing the provided answers. If any exercises seem irrelevant, you can skip them and instead write a justification as to why they are unimportant. These justifications will help us improve the lesson for future students.

Exercise 1

Why do we write articles for our website?

Answer

We write articles to help us pursue our company mission of sharing knowledge and to accord with our company values of learning.

More specifically:

  1. Individual Learning – Writing about a topic is one of the best ways to learn about it
  2. Team Learning – To produce educational resources for developers on and off our team
  3. Marketing – Content will improve our search ranking, helping clients find us
  4. Sales – Sales leads will see that we are expert software developers

Exercise 2

What is a static site generator?

Answer

A static site generator is a type of website generator that creates and serves the same HTML files and content for all users, regardless of individual user preference or activity. In contrast, a dynamic site generator creates unique content each time the user requests a page, based on that individual user’s interaction.

A social media website that shows each user some content that has been specifically curated just for them, or provides features based on individual account preferences or location, would be an example of a dynamically generated site. A blog that shows everyone exactly the same thing would be an example of a statically generated site.

Using a static site generator has many benefits, most notably the speed at which the pages are served to the user.

Exercise 3

Clone the website from github and set up a local development copy. When you execute the ./run script, a browser tab with our website should open at 127.0.0.1:4000. Create a new article that is inline with our Mission and Values, and place it in the proper location in the /articles/ directory. It must include at least one image. Add your images to /img-orig/, and run Makefile to make your images propagate. When your article is well formatted, and compiles correctly, create a new branch and pull request, and assign it to a lesson mentor. The available lesson mentors are included in the YAML front matter of this lesson.

Hint

Read through the README and be sure the system dependencies have the appropriate versions.

If you are using macOS and you want to use nvm to manage your node versions so you can use older iterations, and you get a terminal result like “-bash: nvm: command not found” follow these steps to install and configure nvm:

  • brew install nvm
  • Create .nvm directory using mkdir ~/.nvm
  • Open your .bash_profile file for editing:
    • nano ~/.bash_profile
  • Add the following code to your .bash_profile, then Press CTRL + X to save and exit the editor:
    • export NVM_DIR=~/.nvm
    • source $(brew --prefix nvm)/nvm.sh
  • Load .bash_profile settings from terminal:
    • source ~/.bash_profile
  • install the required version of node with nvm
  • switch to the required nvm version with:
    • nvm use <version>

Read about our standard script names.

Exercise 4

How do you create a new 10x lesson?

Answer

You’d need to create a new file in the 10x/lessons/_posts directory. The file should include the sections described here.

Exercise 5

How do you add images to the website?

Answer

New images should be added to the img-orig folder. You then run the Makefile to compress them and send over the image to the img folder. In the markdown, you’ll refer to the compressed images in the img folder.

Be sure to include an alt tag for images. Also, be sure that images have an appropriate size. Large images are a great way to slow down the site.

Exercise 6

What is the purpose of the _includes directory?

Answer

These are small reusable snippets of markup that let us avoid duplication. They’re kind of like React components.

Exercise 7

How do you add styling to the website?

Answer

In order to add styling to the website, you will have to edit the .scss files for your relevant section. For example, if you want to add/edit the styles for articles, you would edit the file scss/article.scss. Once you edit the file, you’ll want to run make so that the .scss changes get propogated to the .css and .min.css files.

Continuous Lesson Improvement

Open the lesson page in the GitHub editor.

Remove any exercises or learning material that are not useful to the intended audience. Find ways to shorten and clarify the writing. Add generally useful exercises, responses, or learning material. Your improvements will make our training program great!

Create a new branch and pull request and assign it to your lesson mentor. The available lesson mentors are included in the YAML front matter of the lesson. They will set up a time to review your suggested changes and to talk through your exercises for the lesson.

After the review add your self to the "completed" property in the lesson's YAML front matter and merge in your changes!