Article

What is GitHub?

GitHub has become a key tool in not only my web development process but also in my life and work.

You definitely don’t need GitHub in order to create web sites, but it can really help you stay organized and productive.

GitHub, as the name suggests, is based on what was once a little-known set of software for synchronizing repositories of software code. Git, started in 2005, is an open source software system for version control of distributed code repositories. (I’ll leave explaining the details of git to another time.)

GitHub is a service layer built on top of git. GitHub was started in 2008 as a small startup. The popularity grew over time, and GitHub now has over 40 million users. In 2018 Microsoft purchased GitHub for $7.5 billion.

GitHub is not the only service of its type. There’s also GitLab, Bitbucket and a few others. I prefer GitHub, personally. I like its interface and additional features. (I’m not interested in debating the pros and cons of GitHub over another system.)

One of the aspects of GitHub I like best are its project management features, particularly issue tracking. Every repository on GitHub comes with a built-in issue tracking system, project management board, and even a wiki. These tools are very useful in any team-based project. But they are also really useful when just working in solitude on your own project.

You can even create a repository without any code and still use the project management tools. Plus, everyone now has the option to make their repositories public or private.

Another tool of GitHub that I emphasize in a course on learning to program is the ability for simple web publishing through GitHub. It’s incredibly easy to setup a website and start publishing your own HTML and CSS code.

Article

Task list for initial prototype implementation

#4 in a series

What do you need to do?

The prototype shows you what you need to do. You then need to convert that into a list of tasks that you need to accomplish.

You can write the list as any kind of document. Don’t get stuck on figuring out the most fantastic task list app. Just write the stuff down.

What do you need to know?

As you create the task list, mark the items that you don’t yet know how to do. (It’s okay if that are all the items, but you probably know more than you realize.)

Initial tasks

For the zoonoses site I’m developing, here’s an initial list of tasks for getting started:

  • organize my file structure
  • setup the base files
  • implement a rough mockup in HTML/CSS based on the prototype sketch

Once you have this very rough prototype as actual site that you can work with, then start iterating. Add different elements. Build on each part incrementally. Before you know it, you’ll have a website.

Article

GitHub as a Tool for Teams

Notes for DCI 190: Shenandoah, a studio course on online literary magazine design.

GitHub, based on the open source tool git, most often functions as a version control system. (There are several other similar tools based on git, such as GitLab and Bitbucket.) I tend to prefer GitHub, though the others are also very good systems and you may very well encounter those in whatever workplace you enter. Version control will be discussed later in the course. Initially, we’re going to focus on using GitHub as a collaboration tool, as a way of facilitating communication among the class, as a project management tool, and as a mechanism for tracking things to do in the publishing on a literary magazine.

If you do not yet have a GitHub account, then signup for one. You can get a free account at github.com.

GitHub Signup page

Don’t freak out by the Built for developers. You don’t have to be a developer to make really good use of GitHub.

In several ways, GitHub is a type of social network. I don’t really use it in that manner, but some people do. And your GitHub profile is public and serves as a good way of showcasing your technical work. Indeed, I’m a bit impressed when I see people place their GitHub address on their CV. You can see mine. Impressed? Uh, well, no? That’s okay. Let’s move on.

Jeff’s GitHub page

Once you have a GitHub account, send me your GitHub username. (Some of you have done that already.) So, what am I going to do with your username? This is where things start to get interesting.

The concept of a repository is central to understanding how GitHub works. Think of GitHub as being organized into repositories of code. Some of you may even be wondering, what really is code? In the simplest sense, code is just a set of files. Code could just be one file but it’s usually many files organized in a single top-level directory and, often, with subdirectories. It’s that top-level directory and all its files and subdirectories that make up a git repository.

Yet, in GitHub a repository also can have no code associated with it. Whoa. It’s not a very common case, but for the purposes of this class we’re going to use a repository on GitHub that has no code. So, for now, just don’t worry about any code. Instead, let’s focus on the other tools that come with a GitHub repository, namely Issues and Projects.

In this class, we will be working with the Shenandoah repository on GitHub, which you can find at https://github.com/wludh/Shenandoah. This is a private repository. So, you’re not going to have access until I add your GitHub username to this repository.

There are three things I want to point out about the Shenandoah repository page: wludh, Issues, Projects.

All GitHub repository pages have a similar structure with a number of tabs along the top. But let’s first talk about that wludh up above those tabs. As students at W&L, you probably have guessed that wlu refers to Washington and Lee University. You might or might not have guessed that the dh refers to digital humanities. So, wludh is simply the organizational home on GitHub for DH projects at W&L. And the Shenandoah project is grouped under that organizational account. Enough about DH for now, but if you’re excited about that then you can browse our dedicated digital humanities at W&L site.

Issues

The way in which GitHub handles issues is one of my favorite features of this tool. What are issues? Ah, don’t get confused because this class is about publishing a literary magazine. In the context of GitHub, an issue is not an issue of the magazine. An issue is an idea, or a thought, or feedback, or a task to do. In the GitHub help, issues are explained under Managing your work on GitHub. That’s a really good section to read thoroughly.

Issues allow for threaded discussions so that you can follow the flow of a conversation. You also can add labels, tags, and milestones to issues. These attributes aid in organizing issues.

We’re going to use the GitHub issue tracking extensively in this course. Actually, issues will be one of the primary ways in which we communicate in this course.

Spend time getting familiar with the variety of ways in which issues can be used in GitHub. Many other tools have similar capabilities. Issue tracking is an essential component of project management. A well-structured set of issues enhances productivity for everyone. But it takes an organized mindset to use labels (i.e., categories) and tags in an effective way. Tools can only aid you so much.

Knowing how to conceptualize a structured approach to issue tracking via the logical use of labels is a skill that makes you a valuable part of any team.

I’ll be talking more in-depth about issues, but it all becomes clearer as you actually start using the issue tracking within GitHub. I’ve created some issues that will help you get started. There are three that I want to call to your attention.

  1. Q&A. This is a general issue where you can post questions throughout the term related to any aspect of the course, whether assignments or technical questions. I’ll also post my answers to those questions in this thread.
  2. Suggestions for enhancements/fixes. This week you should be looking through the online issues of Shenandoah and identifying enhancements and fixes for the site. We’re going to talk about those in class on Friday morning.
  3. Weekly reflection. A separate issue exists for each week of the course. (The dates are the Fridays on which the class meets.) Prior to class, post an individual reflection of what you learned this week. You’ll be doing these reflections for every week of the course. Essentially, this is a way to get you to think about your own thinking. It’s a good habit to get into for anything that you do. As for grading: the only way to get this wrong is not to do it. Your reflections will likely improve week-by-week.

I’ll talk about the Projects part of GitHub in another posting. Projects are directly connected to Issues. For now, focus on getting comfortable with issues.

To do:

  1. Signup for a free GitHub account
  2. Send me your GitHub username
  3. Look through Shenandoah and make suggestions in the issue tracker for enhancements and fixes.
  4. Write a weekly reflection in the issue tracker for this week.
  5. Let me know if you encounter any difficulties.
Article

Teaching with GitHub

Several of my courses could benefit from a unit on GitHub. I want to devise a series of lessons that could be plugged into any of these courses with only a slight amount of modification specific to the actual course. It’s easy to identify the aspects of GitHub that I want to cover:

  • version control
  • code sharing
  • issue tracking
  • project management
  • public and private repositories

But I don’t want to start out course planning from a content coverage perspective. Increasingly, I’m trying to adopt an approach learned from Understanding by Design. It’s an approach that most closely mirrors my own approach towards my work and even my life.

This morning I jotted down several questions on a legal pad. I revised these into two essential questions:

  • What workflow is most supportive of collaborative development?
  • How can my choice of work methods enhance my productivity?

These questions place GitHub within the context of productive workflows, which explain why we’re even thinking of talking about it in the first place.

Getting organized is the first task for any development project, but in teaching coding, the introduction of GitHub is not the first step to learn. In helping students understand HTML/CSS, introducing GitHub too early could add a huge layer of confusion. I like for students to understand the simplicity of the web before they understand tools for enhancing productivity.

Article

Interlitq: from custom PHP to WordPress

Earlier in the year I described the essential elements in redesigning a literary magazine with Interlitq as our case study. The Interlitq redesign continues. The current timeframe is a June completion date, which is delayed from my original intention of April. The delay is largely due to my teaching schedule. I completed the multimedia storytelling course, which had a complex web project, in April. And barely more than a week later started teaching an innovations in publishing course during our mini-spring term, which is just 4 weeks. Once spring term is over, I’ll have more time to wrap up the Interlitq project. Also, I have a graduate student from the University of Tennessee School of Information Sciences collaborating with me over the summer on literary magazine redesign and library publishing.

Quantity

Let’s review the quantity of material that has been published in Interlitq since its origin in November 2007: 26 issues + 6 ongoing series. That represents over 500 contributors in a variety of genres (essays, interviews, poetry, fiction) as well as more than 20 artists contributing nearly 200 works of art for illustrating the publication.

Content Management

That amount of material requires a content management system (CMS). Since its beginnings in 2007, Interlitq has existed in a set of custom PHP files where each work (essay, interview, poem, story, etc.) was stored in a separate PHP file. Each contributor biography also existed in a separate file. While static sites offer significant advantages, the integration of content and code and style in this fashion is a nightmarish scenario for migrating to a new design and more efficient form of publishing. The Interlitq site consists of over 4,000 files that need migrating to a new system.

For the redesign, I chose WordPress for the CMS because of its broad level of support and customization. While a tool like Grav presented a lot of interesting possibilities, I simply wasn’t ready to jump into developing a Grav-based site considering the limited time availability I have for working on this project.

Blog

The Interlitq blog has existed separately on wordpress.com since the blog started. With this redesign we will be bringing the blog into same new design as the overall site. The blogging component gives WordPress another advantage since WP is a premier platform for blogging. And, honestly, another reason for choosing WP is that I’ve worked with it since 2004. So I’m very comfortable with the WordPress way.

New Design Aspects

Let’s look at a few new design aspects that will be appearing in Interlitq.

Archives

The previous design had a listing of past issues as show below.

The new design is a grid layout of issues and series represented by its distinctive artwork.

The CMS allows the grid to be automatically generated when a new issue or series is added.

Contributors

One of the more problematic aspects of the old design is that the contributor list simply existed alongside the left column of the page. That worked fine for the first few issues but now with hundreds of contributors, the list scrolls far beyond the footer of the page:

A database-drive site allows for the contributor listings to be presented in a dynamic manner that features the author photo with the author’s name (which is actually a link to the author’s full bio on the site). This approach also allows optional text to exist below each author photo. For the prototype below, I simply added some placeholder text but this text could be a quote from the author’s work on Interlitq:

Obviously, this represents a small sample of the hundreds of authors that appear in Interlitq. The alphabetical row above the author photos allow for the contributor list to be segmented into smaller group for displaying on the page rather than loading the giant list all at once.

 

Article

Interlitq: identifying essential elements in redesigning a literary magazine

The redesign of Interlitq is going extremely well. We’re on a timeline to have the redesign completed this spring, and aiming for an early April release if at all possible. A literary magazine is one of the more complex types of sites to redesign. On the surface it looks quite simple: modify the header, adjust the color palette, update the typography and call it done. But there’s much more once you dig into all the elements that make a literary magazine on the web.

Branding

In continuous publication now for over a decade, Interlitq has retained the same design since it began in 2007. Yes, that now looks very dated but there are aspects of that design that form Interlitq’s visual identity. And we don’t want to do away with that entirely. Rather, we want to strengthen certain aspects and create a fresher set of visual elements through typography and judicious use of white space.

My opening step in any redesign is to pull out some graph paper and a pencil. Then I start sketching ideas that seek to uncover the overall structure of the site. Some of the graph paper ends up crumbled and tossed to the corner of the desk. Eventually, I find some drafts that capture the essence of each page of a site.

The first element a person encounters upon entering the website is the header. Here’s the (almost) original header from 2007:

I say almost the original header since the site did not originally include a blog. The blog tab was added a couple of years after Interlitq started. But the coding for the blog tab in the header was programmed so that it also appeared in the header of earlier issues as well. One thing to note that is now a historical artifact of web design is that this header image actually consisted of 10 individual images, plus 14 spacer gifs, all set within an HTML table. Actually, it’s an HTML table within a table. That was the complexity of web design in the early 2000s! But it looked good for the time, and it worked. Yet, there was something about the branding that wasn’t clear, e.g., was the site named Interlitq (or interLitQ) or was it The International Literary Quarterly? Or was The International Literary Quarterly a subtitle or simply a description of the interlitq.org site?

In 2010 a new header was designed for the site that solidified the branding on Interlitq as an original and memorable brand for the site. And the new header retained the thematic color scheme of the original.

The result was a slimmer header with a clearer emphasis on the Interlitq brand. This header still had the same problem, though, of being built out of multiple images. In the code the images have unwieldy filenames like menu_r1_c2a.gif.  Here are examples of a couple of individual images that comprise the header:

Dealing with multiple images in a header menu is a technique of the past thanks to advances in CSS, the coding language used to style web pages.

I knew that any redesign needed to start with figuring out how to design the menu in CSS without using any images. Only the web tech readers of this post will realize how exciting that is! And, also, how important. Through using only text-based CSS in styling the header, then we can create a site that works well on all types of screens, including cell phones.

The new header uses no images and consists only of code. (Okay, for the simplicity of writing this post, I’m cheating a bit by using a screenshot of the new header but, believe me, it’s all code and looks very crisp and clear on the actual site.)

The entire header and menu is created through CSS, including the rounded corners on the lower edges and the slight shadow. The color palette has been updated and the type is all web-based.

One of the remarkable aspects of web development that enable non-image based design are web fonts. For Interlitq I chose two fonts from the freely available Google web fonts service: Cormorant Garamond and Lato. In the header, the word “Interlitq” is set in Cormorant Garamond and the text of the menu is set in Lato.

Home page and landing pages

The home page of a literary magazine, the web page you see when you enter the main address of the site, e.g., www.interlitq.org, often serves multiple functions. In the early years of Interlitq, the home page served as the introduction to each issue. At that time, Interlitq only published issues quarterly. Below is a screenshot of the very first home page for Interlitq, which also was Issue 1 in November 2007.

That page was really functional. The main text on the page was an introduction by the editor. A list of contributors appeared in the left side column and the masthead just underneath the contributor list. (Again, note that the header menu in the image above is the only part that differed slightly.) Though information about each author’s work is embedded in the editor’s introductory text, one essential element that is missing is a table of contents for the issue.

The home page for issues of Interlitq has been redesigned to the following layout:

Noticeable changes here is an emphasis on an actual table of contents that gives prominence to the work of each author. The titles are the works are displayed as hyperlinks next to the authors. The works also are grouped by genre.

The next post in discussing this redesign in progress will examine how to handle the home page when the literary magazine switches from issues to publishing individual works on an irregular basis. That presents some challenges but can be handled quite well.

 

Article

Interlitq: technology for 2007

It’s November 2017 and Interlitq: The International Literary Quarterly is 10 years old. Now, we’re not only redesigning the site but reworking the technical architecture from the ground up. One key question: do we migrate all the content from the last 10 years into the new design and architecture, or do we just start fresh with new issues going forward? The latter is the easy choice but there’s so much value in the first decade of Interlitq that it all deserves to be in the new design and technical architecture. We know that’s the right thing to do, so we’re doing it even though it’s not the easiest approach.

Before we go further, a few words about how we got to this point. I first heard about Interlitq in mid-2017 while having lunch with Peter Robertson in a restaurant in downtown Buenos Aires. I had known Peter, a Scotsman, for about a year. We both lived as expats in Argentina and found a connection through our mutual interest in literature. He mentioned that he was starting a literary review, but I didn’t really get involved until issue 2.

The site was developed and designed by an Argentine that Peter knew. The site was not done in any type of content management system (CMS) but as custom PHP code. That worked fine for a few issues but scalability has become a major problem for Interlitq. The graphic design looked good for 2007. (Really, it did.)