How to improve readability of highly-structured text

Question

NOTE: This question explores methods for increasing readability for a target user group.

Background: Readability is invaluable when dealing with large amounts of text. For some users, programmers, that text represents "objects" in a computer system. These objects often have a hierarchical structure (i.e. objects have parent-child and sibling relationships with other objects). Traditionally, these "nesting" relationships have been communicated to the user by increasing the left margin to show which object belongs to which (the child object is indented greater than its parent, and siblings start at the same level as each other).

The Problem: On one hand deeply nested code is hard to read. On the other hand, visualising nesting levels are necessary to understand code. De-nesting code/html requires a lot of effort, which only improves readability, not actual code effectiveness, accuracy etc.

Is there a way to communicate hierarchy other than adjusting indentation?

I will provide a small piece of sample text, along with my first attempt at making it more readable using some colors, shapes, etc. I'm sure someone can do a better job. Let's make a breakthrough together!

Normal nesting using white-space (text version):

Attempt 1: show nesting in margin:

attempt 2: add shapes in code to show level:

attempt 3: replace filled overlay with bordered area markers:

Answer 1

"The Problem: On one hand deeply nested code is hard to read. On the other hand, visualising nesting levels are necessary to understand code. De-nesting code/html requires a lot of effort, which only improves readability, not actual code effectiveness, accuracy etc."

1st thing: Do you know that 'de-nesting' improves readability for sure i.e. you or others have done a test which shows the indenting causes a problem rather than just understanding a program being actually hard? It may be generally easier to read text if aligned nicely but programs are a different kettle of fish - the code isn't necessarily sequential for one - there's conditions, callbacks etc which mean the code structure plays as much a part as sequence.

Program code is usually displayed as an indented tree (using white space) to show the nesting level of the structure, as in the first method you show. By attempting to replace the white-space with a colour coding, you're attempting to replace the most powerful perceptual cue for quantitative information (position, in this case the horizontal component) with a colour coding cue which is generally accepted as being more useful for non-quantitative data (i.e. categorical data). You've implicitly accepted that fact in your next 2 solutions by having the colour coded bars in the margin indented anyways even when the code is fully left aligned

Have a look at this past work to see if what you're doing is actually a good idea:

Program indentation and comprehensibility Authors: Richard J. Miara Univ. of Maryland, College Park Joyce A. Musselman Univ. of Maryland, College Park Juan A. Navarro Univ. of Maryland, College Park Ben Shneiderman Univ. of Maryland, College Park

http://doi.acm.org/10.1145/182.358437

Their findings were:

Two styles of indentation were used--blocked and nonblocked--in addition to four possible levels of indentation (0, 2, 4, 6 spaces). Both experienced and novice subjects were used. Although the blocking style made no difference, the level of indentation had a significant effect on program comprehension. (2--4 spaces had the highest mean score for program comprehension.) We recommend that a moderate level of indentation be used to increase program comprehension and user satisfaction.

Most rated zero indentation to be poor. It's a old paper sure, but there's not much better/newer out there

Answer 2

As a person who's studying programming, I don't think it's a broadly applicable problem, but rather a problem affecting a subset of use-cases.

For example, object-oriented languages (Java, Kotlin, C++, etc.) lend themselves to splitting code up into atomic functions, so if you have very deeply nested elements, you just need to restructure your code (and you'll be better for it).

Now, with some markup languages like XML, you have a point.

Just remember, any solution you have will only suit specific use-cases. In OOP, encouraging less nesting is a feature, not a bug.

As for alternative ways of showing hierarchy, off the top of my head:

• Typography. There's lots of things you can do with type. Think headings in standard documents. You can change the size, tweak the color and opacity, change the case, and play with different font weights. Aside from color and opacity, I don't think any other indicators would work well, but it never hurts to try.
• Spacing. You may use different margins for different hierarchy levels.
• Enclosure. E.g. use lines and shapes to delineate sections.
• Interaction. Play with interactivity. Interaction can make deeply nested code more usable, without removing indentation as a cue. One frequently used pattern are collapsible sections, but you don't have to stop there. Any of the other hierarchy indicators listed here can be made interactive. For example:
  • Color. The active line and its children could maintain its color, while the rest turns dim gray.
  • Spacing. The active section could be separated with vertical margins.
• Separate areas. This ties in with interactivity. You could show hierarchy using columns, with the first column being the top level, the second column being its children, and on and on. You could show children on a separate page, in a dialog, or an expandable section.

Lastly, I recommend reading more about Gestalt psychology. It deals with how we mentally group items.

Answer 3

If this was simply text on a page then the normal conventions of varying the font size and spacing between lines of text would be more than sufficient to deal with the level of hierarchy and structure (although you could certainly try to apply some of it as well). However, in this instance it is not necessarily true that the content at the top of the hierarchy is more important compared to the content nested deeper (e.g. just wraps everything up).

Lets use the examples you have provided and see how they can be improved to illustrate what is important when visualizing content in hierarchy.

Normal whitespace

The problem here is that the only hierarchy represented by the whitespace is the depth of the nesting and not the hierarchy of the page, which still needs to be interpreted by going through each line and understanding the structure, and also it becomes more difficult to distinguish the hierarchy as more levels of nesting is introduced into the code. Clearly there are more dimensions to visualize then there are ways to represent them, so you need to introduce more elements.

Show nesting in margin

The use of the vertical bars to represent code at the same level of hierarchy is a way to address the problem of just using white space, and adding colours helps to make the different levels even more distinguishable. However, this is still a solution that cannot be scaled easily when you have too many deeply nested layers, and still only solves the problems of helping people identify the depth of the nesting but not the semantics of the hierarchy.

Shapes and border markers

Not really sure that it adds much more value to what has already been done with the bars in the margin, and in fact this is probably an example of overloading the visual representation so that it actually increases the amount of visual information that you have to process without too much additional benefit. If you compare it to the previous solutions you'll find that it is easier to process the hierarchy information without having to look at the code compared to having the colours, shapes and borders mixed in with the code.

An alternative

Use the vertical bars in the margin to show the hierarchy because I think it is the most minimal way to represent hierarchy. I like the idea of colour coding the blocks of code (both in the vertical bars and the shape/border) but you should match it with the type of HTML element and not the hierarchy because then you lose the ability to encode two different types of information at the same time. In the example you showed two elements at different hierarchy coded in different colours when they could be the same colour but having different depth of the vertical bar to show that they are the same element at different hierarchy.

Actually, I have seen HTML editor (or text editors in general) that allow you to expand and collapse nested code when the syntax of the content is specified. These editors allow you to also expand and collapse the code at specified levels of hierarchy and is therefore a much more efficient way of accessing the content (i.e. they allow you to navigate the hierarchy instead of only visualizing it).

The suggestion of opacity by Tin Man is quite interesting, as it offers a way to show the depth of nesting combined with focusing the users attention to the area that they are interested in. But rather than a fixed visual cue, you could introduce some interaction to make this relative to the level of hierarchy you are currently at, so that as you move down the hierarchy you decrease the opacity of the levels below.

Answer 4

One option is to use the "collapse" and "expand" ability for code blocks. Something like this

Answer 5

Illustrating code hierarchy by using the left margin is common because it is effective¹, though I sympathize with your view that it can become tedious to work with. Thus, I think the issue we should try and solve is not illustrating hierarchy in some other way, but rather provide tools that make navigating this code less tedious.

Visual Studio provides an option for the user to view a preview of their code as they hover over the scroll bar. This preview automatically shifts the code to provide the most effective "fit" for the hovered region.

You could incorporate this same auto-fit mechanic which will automatically reduce the left-margin based on what content is currently visible in the editor.

Alternatively, you could allow the user to link this behavior to a hotkey + click action that will automatically adjust the horizontal scroll bar to situate the beginning of the selected line to the left edge of your editor.

For example, if you configured this shortcut with Shift + click:

    <div>
        <ul class="list">
            <li> <!-- Shift-click here -->
                 Hello World
            </li>
        </ul>
    </div>

Scrollbar position:
[<][=====]                                     [>]

clicking on the <li> line would auto-scroll your window to show

class="list">
<li> <!-- Shift-click here -->
    Hello World
</li>
>

Scrollbar position:
[<]      [=====]                               [>]

---

¹ Source: Personal opinion/experience.