0

I've been writing down an Online Manual for a programming library, and the service I'm using (ReadTheDocs) allows me to use plenty of HTML features in Markdown + JavaScript besides integrating nicely with my other content.

As far as I know:

  • Users want the information they want in the least amount of time possible.
    • The longer it takes to find the information the worse it is
    • Clutter also impedes this
  • For the most part with manuals, it is unavoidable to have to sift through a certain amount of uninteresting stuff to get to the money.

Based on this, I've come up with the following layout for my Installation Instructions Chapter which attempts to keep everything regarding it in one page, however information of interest stays hidden until noted otherwise:

enter image description here

If everything were to be simply open, the clutter speaks for itself specially since some of the content is almost the same for both cases:

enter image description here

So, I'm at a conundrum between what's more user-friendly for a digital/web manual: Making more, shorter pages for a chapter where users will have to search for, click through and load (0% clutter); or making large chapter pages where the topics are simply hidden?

With anchors and links I can make buttons that take users anywhere in both cases, but from what I've seen people interacting with the page they ignore the links in the Table of Contents entirely for the most part, and just scroll down until they find what they want.

Improve this question

1 Answer 1

Reset to default
1

It depends of the total structure of the manual, is it long or just the gif you shared?

First, think about the information architecture and how you are going to distribute it.

Let's think first about the hypothetical situation of the structure of your gif. Read a bit about this: https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two

If you have, let say:

Pages:

  1. Foo Summary

  2. WIP Fundamentals of Foo

  3. Installation Guide

    3.1. Windows Install

    3.2. Linux Install

    3.3. Download links

  4. Getting started with Foo

    4.1. First steps

    4.2. Shortcuts

    4.3. Advanced techniques

  5. Examples

You have 11 hypothetical pages, so you almost follow the rule of 7+-2.

I would unfold all the categories, so the user will fast scan all the option and go to the most relevant information for his situation, and he will know the extension of the manual, since with these few options it doesn't worth to use an acordeon. The user will find the information in a fast way.

I would fold (or even delete) the 3rd level pages, since they are short enough to create a submenu in the submenu. The user will click on Windows installation and there he will find 2 sections, anaconda and or python 3, fast scan the titles and go for the information that he needs.

If you have more than, 20-25 pages, fold them and use relevant copys for each category of the menu.

Improve this answer
2
  • While my intent was to refer only Installation Instructions where I have these different steps for different kinds of users and wanted to make it more straightforward, this answer brings some nice concepts to consider. Should an "accordion" type of drop for the index category be there only if there's more than 7 subcategories inside, or?
    – lucasgcb
    Apr 3, 2019 at 10:53
  • Roughly speaking between 5 and 9, but do not follow this rule strictly. If the information are like 12-14, it doesnt worth to use an accordion, you are hiding vital information to the user.
    – Juan Jesús Millo
    Apr 3, 2019 at 11:03

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.