---
title: "Pages at a glance – the importance of the first two sentences of any topic"
date: 2018-09-15
description: "Implementing “Pages at a glance” in Jekyll The importance of the page summary Enforcing best practices with structure  At my work,..."
canonical_url: https://idratherbewriting.com/2018/09/15/pages-at-a-glance-feature/
---
# Pages at a glance – the importance of the first two sentences of any topic
![Showing sections at a glance](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/digitaloceansummaries.png)

It took some time to win me over to this idea, but I finally saw the light. Particularly, when I realized that the overviews should contain brief summaries of each page, and not just a list of the page titles (which is already visible from the sidebar), I agreed that this approach would improve doc usability. As I implemented this in some of my docs, I ended up calling this feature “Pages at a glance.”

Here’s a quick demo of “Pages at a glance” with Fire TV:

![Showing sections at a glance](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/firetvdocssummaries.png)

The idea is that users who see the section title in the sidebar can click the folder title and get a better sense of the folder’s contents at a glance. In the section overview, users can view the page title followed by the first two sentences (or 200 characters) of the topic.

This design principle aligns with an article in my Simplifying Complexity series — specifically, [Principle 4: Reduce and distill vast information down to its essence](/simplifying-complexity/reduction-layering-distillation.html). (In fact, I even added the “Pages at a glance” explanation into a new section there called [“Showing section summaries at a glance”](/simplifying-complexity/reduction-layering-distillation.html#summaries_at_a_glance).)

As a general best practice, section summaries follow the idea of progressive information flow to provide users with an increasing amount of detail as desired. The progression goes somewhat like this:

The flow of information moves from condensed to more detailed. This allows users to more easily navigate the information to determine whether its relevant to them. Each of these elements distills the larger information into small, easily consumable units that the reader can quickly process.

What you don’t want to do is drop the reader into a collection of long pages that don’t provide any kind of up-front summaries or distillations of what they contain. In those scenarios, the user would likely resort to Ctrl+F to try to find keywords on the page.

## Implementing “Pages at a glance” in Jekyll

To implement “Pages at a glance” in Jekyll, I basically just added a frontmatter property called `folder` and a `weight`. Then I used a `where_exp` filter to get the content. Here’s the code for this include:

```liquid
#### Pages at a Glance

{% assign folderKey = {{include.folder}} %}
{% assign folderPages = site.docs | where_exp: "item", "item.folder == folderKey" | sort: 'weight' %}

{% for folderPage in folderPages %}
[{{ folderPage.title }}](../{{ folderPage.permalink }})
{% if folderPage.description %}{{ folderPage.description | strip_html | strip_newlines | truncate: 200 }} [more »](../{{folderPage.permalink }}){% else %}{{ folderPage.content | strip_html | strip_newlines | truncate: 200 }} [more »](../{{folderPage.permalink }}) {% endif %}
{% endfor %}

```

You call the include like this:

```liquid
{% include pages_list.html folder="fire-app-builder-get-set-up" %}
```