Do some technical documentation websites purposely have very plain design?

Question

I notice some widely read/important websites, all technical documentation pages in my examples, have some really old, dull and seemingly poor design.

Is this on purpose? Is it based on UX considerations?

I imagine the maintainers of these websites have the resources to build a nicer looking website or even have the skills to do so themselves, so rather than assuming they're just being lazy, I wonder if there's an actual reason why the design is so simple? And, if there is, then I'd guess it for UX reasons (even though I have no idea why. Very little navigation/searching ability, no colour coding, etc).

Any guesses?

Here are some examples I'm talking about:

GCC - https://gcc.gnu.org/install/configure.html

A random page from a binutils command docs - https://sourceware.org/binutils/docs/ld/Options.html

A random page from Linux manpages - http://man7.org/linux/man-pages/man3/acl_calc_mask.3.html

Answer 1

In design, you always have to ask: Who is the user and what is his or her intent?

With technical "user manual" pages, the user is probably an engineer or sysadmin trying to find information as quickly as possible in order to get something installed or fixed. They are likely:

• Searching for keywords
• Reading just a section at a time
• Not using their main computer/browser. They might be on a whole different machine, reading the page on a phone without wifi, or even reading from a print-out of the website.

Things that will get in this user's way and impede tasks:

• Lots of navigation, labels and links that trigger the same search words
• Slow-loading images, scripts and page "furniture"
• Lots of HTML formatting carrying over when they're trying to direct-message this information to a colleague

Another user to think about on these pages is the person who maintains them. Their job is to be accurate and quick. Their job is not to know HTML and CSS as a marketing web designer would.

If you look beyond aesthetics, the pages are designed pretty well for these users -- they're organized in a clean, hierarchical way with section headers, appropriate tables, and lists.

Answer 2

Something to keep in mind is that all of the documentation pages you have linked to are for tools which are designed to be used from text-only interfaces. It makes sense, then, that the documentation would be in (mostly) text format as well.

The manpages site in particular has been designed to look exactly like a man page from a Unix terminal, probably as this is the format that developers are used to seeing. The others, as noted by Stacy H, are designed to be text-searchable. Ctrl+F is king.

Code documentation can also be sparsely-styled because it is procedurally generated from comments within the code (using tools like Sphinx) and doesn't have much attention paid to its appearance, but there are examples like the ReadTheDocs theme which are designed to be more user-friendly. It may be that the documentation was written a long time ago and only updated piecemeal since then, and in the case of GCC that "long time ago" happens to predate the widespread adoption of CSS/JavaScript. It's a bit of a meme that developers hate writing documentation, so it's possible that no-one has volunteered to update it (and these are open-source projects, so a volunteer effort would be required).

Answer 3

tl;dr Yes, because of a design school of thought called "Content is King."

… old, dull and seemingly poor design.

All of these are subjective. "Old" to many people equate to "familiar," which means they won't have to learn to learn to navigate yet another design. "Dull" is fine, it's technical documentation after all. Sprucing it up with design isn't going to make the content any more exciting, and might even result in cognitive dissonance as all the dancing unicorns contrast heavily with the text. And "poor" must always be judged with empirical data in relation to a goal (see for example Nielsen Norman Group's excellent reports and especially Jakob Nielsen's articles summarizing the reports). Presumably the primary goal of documentation sites is to allow people to find the relevant documentation quickly. A secondary goal is for the people creating the documentation to be able to do so with minimal effort, since no project has infinite resources and documentation has to be updated frequently.

I imagine the maintainers of these websites have the resources to build a nicer looking website or even have the skills to do so themselves, so rather than assuming they're just being lazy, I wonder if there's an actual reason why the design is so simple? And, if there is, then I'd guess it for UX reasons (even though I have no idea why. Very little navigation/searching ability, no colour coding, etc).

It's for the same reasons as above: content is king and resources. As for the specific features you mention:

• In my experience navigation is often way too coarse (a small number of sections with a huge amount of text each), way too fine-grained (hundreds of sections with a couple paragraphs each), or the sections are named using unfamiliar terms. This conditions users to open the whole manual as a single page and use the browser text search function to find what they're looking for.
• Search is usually really badly broken on documentation sites, at least by current search engine standards. Usually synonyms are not found, speling mistakes are not corrected, using a hyphen before a word doesn't exclude it from the results, quoting a multi-word string doesn't search for that whole string, etc., all of which conditions users to just ignore that functionality.
• Colour coding is only useful so long as it actually works. Automatic language detection can be flaky on small code snippets, for example, and I've never seen a code highlighter that can actually deal with Bash, one of the most common languages out there.

Side note: Edward Tufte's books, especially The Visual Display of Quantitative Information, show plenty of examples of excellent visual design which could often be classified as "plain" but are still excellent at conveying the relevant information.

Answer 4

i don't think this is the case in general. There are plenty of websites with technical documentation that have great design.

a few examples

https://developer.apple.com/design/human-interface-guidelines/ios/user-interaction/gestures/

https://docs.angularjs.org/api#angularjs-modules

https://lxd.readthedocs.io/en/latest/

In terms of design do you mean the aesthetics or ux and usability. The main purpose of these kind of websites i imagine would be more towards being able to find/navigate information easily, meaning more focused on navigation and clear information.

I also find that more non technical customer focused and facing websites would have more design resources and effort put into them compared to these, so there's a likelihood for these kinds of websites to feel more dated or neglected.

The links you posted are more likely to be read by power users who would make more effort to find the information they need regardless of the design or usability of the website.

Answer 5

Bjarne Stroustrup gave the canonical answer to this question. Quoting from the FAQ on his homepage:

Q: Why don't you make your website look modern?

A: I'm a "contents provider" not a website designer. I can use my time to improve the contents or the looks, but not both.

What looks "cool and modern" to someone is often considered bad taste by someone else, and fashions change fast. Also, very plain html downloads and displays faster than anything else, and many people still suffer from slow web connections.

The Q&A has not been changed during the last decade or two. It uses a UI which was designed about 4000 years ago: Alphabetic script. This UI has generally been found useful and is considered timeless by many.

Answer 6

For the Linux example specifically, the original documentation for Unix was designed to be printed on paper, since back then graphics terminals were too useful for displaying graphics to "waste" them just showing text. (And you didn't waste time repeatedly printing out documentation on an affordable printer that produced about one page per minute - you kept the printed copy somewhere you could find it!)

Anybody who learned Unix back in the 1980s (that includes me) is very familiar with the original layout of the man pages they refer to often, and "improving" the design simply slows down the user experience of finding exactly what you want to look up.

Answer 7

Although such features aren't used as much today as historically, many browsers allow users to configure various aspects of how web sites should be displayed, such as the fonts, sizes, and colors to be used when rendering. If a web site doesn't explicitly set any of those traits, but the user of a browser sets them to his liking, the web site's content will be displayed in whatever manner the user would prefer.

For a web site to take control of such issues was once considered an imposition of the web site designer that he knew more about what the reader would want than the reader himself would. Of course, it is now normal and expected for web sites to push a certain "image", rather than merely trying to display text in whatever way a user would prefer, but such behavior makes life harder for users who may e.g. have poor vision and need to use fonts which are much bigger than most users would prefer. Some web site designers figure that if there's no reason not to accept whatever styling a user has chosen as a default, they should simply use that styling.

Answer 8

A lot of technical documentation like this is auto-generated by various tools. The manpages are a good example of this. The input (which is written by humans) looks like this:

.Dd March 23, 2002
.Dt ACL_CALC_MASK 3
.Os "Linux ACL"
.Sh NAME
.Nm acl_calc_mask
.Nd calculate the file group class mask
.Sh LIBRARY
Linux Access Control Lists library (libacl, \-lacl).
.Sh SYNOPSIS
.In sys/types.h
.In sys/acl.h
.Ft int
.Fn acl_calc_mask "acl_t *acl_p"
.Sh DESCRIPTION
... etc etc ...

The primary purpose of this is to generate the documentation that you get when you run the man command on the console. Someone rigged up a way to use the same input gibberish to generate HTML output that you can view through a web browser. Since the input language was originally designed for console output, it doesn't support the sorts of things that you'd need for generating rich web output. Even if these features existed they wouldn't get used, because the primary use for these files (the man console utility) wouldn't be able to use them. Some online manpages look slightly better than others, but at the core you're still limited to the handful of basic text effects that a console can handle.

Your binutils link is similar. You can see the original source for that page here. The documentation is written in LaTeX, which can be compiled for many different forms of output (HTML being one of them). The documentation for gcc uses a similar system.

With any of these systems that generate documentation for multiple output formats, the output will generally be limited to the features that all of the various output formats support. In a lot of cases, that common subset is extremely limited, and you get rather plain output.

Also, pay attention to the specific types of software that you're linking to. That's all low-level systems software. The people that work on that type of software (myself included) don't typically go anywhere near a graphical interface. Designing nice-looking, modern web documentation isn't really their background, and the people that can do that sort of thing aren't typically attracted to low-level projects like that. The "pretty" documentation that you see is frequently for higher-level software like web frameworks, where the developers are more likely to have experience with that sort of thing.

Answer 9

Because they were designed to be read on a terminal

man pages are designed to be shown in a terminal. As such, there is a very basic set of formatting available. You can read about the format on roff(7), but basically your target was a terminal or a printer. There is some formatting available, but you can't count on color-coding something that I will read over a telnet link (ain't I lucky?) on my monochrome phosphorus screen.

You can read about the headers and conventions used man pages at man-pages(7). This provide coherence even though they are typically developed by completely different people.

info(5) format provides somewhat more options, and you will find long manuals in that format, as opposed of man pages that fit in about a single page. gcc and binutils documentation are actually written in texinfo, from which it is then compiled into different formats: man, info, html, pdf, etc.

This is actually since the developers can write it once, and have the same content on multiple formats. It is better not needing to keep the versions of several documents synced (some projects do, though). The GNU project states that the documentation MUST be available in info format, which leads to its prevalence.

You could have different themes applied, but you are restricted by the actual structure of the underlying actual content. Some projects choose not to make man/info pages available, such as 7-zip whose docs are in html. I find that annoying, but that may be just because I am used to finding the manual of utilities directly from the terminal. Nowadays, it is common to be connected to the internet, but it didn't use to be so. Plus, accessing the manual page from the actual system -to which I may be connected through ssh, so no fancy images- means you get the manual of the version you have currently installed, not a future version or a different flavor. Compare sed vs sed vs sed vs sed vs sed.

Finally, you should take into account that technical documentation is usually made by developers. Which means the technical documentation is, well, technical, with the goal of communicating a few select points, like the parameters that it supports. It is good to be consistent and familiar to the developers. So bells and whistles wouldn't be appropriate.

Do note that info manuals do show (in HTML) a navigation structure, however. They may not feature a search engine (that feature would require server side support, whereas generated files can be just uncompressed in a web path), but they do offer a one-page version, where you can easily Ctrl-F from your User-Agent any desired term.

Answer 10

The greatly loved and greatly hated Richard Stallman's* personal website is a classic example of the plainest of vanilla presentations. He probably has access to and awareness of about as many 'free' website creation / presentation packages as anyone.
[*Chief GNUisance of the GNU Project and of Free Software Foundation fame]

While this is a personal website, portions of it would be properly described as a "technical documentation website", and the presentation style is consistent throughout.
Perhaps "naive simplistic" ? :-)
It's no mistake :-).

Richard has 'a number of axes to grind' and it seems reasonable to consider the style of presentation as being intended to 'make a statement'.