40

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

  • 39
    Here's my "ideal" for technical documentation: tools.ietf.org/html/rfc793. It's concise, it's easily searchable, it's bandwidth friendly, it can be displayed on any device, and it links directly to any/all applicable external references. – FoggyDay Apr 11 at 22:23
  • 20
    @FoggyDay I'm sorry, but your "ideal" technical documentation isn't even hypertext? – user371366 Apr 12 at 5:50
  • 51
    As someone who regularly uses such resources, please do not go and mess them up with ghastly animations and grey text on a grey background, and rubbish menus and such. – Adam Barnes Apr 12 at 14:01
  • 13
    For an example good API doc design, check out the jQuery or lodash documentation. Function parameters, descriptions, types, examples, common pitfalls, links to the source, "version since", simple and working search functionality, and no extra noise. – BlueRaja - Danny Pflughoeft Apr 12 at 18:38
  • 20
    "Old," "dull", "simple," and "poor design" are not synonyms. In a sense, there are several questions here: Why are these sites using old designs? Why are these sites using dull designs? Etc. While "old" and "simple" apply to most of the given examples, I'd argue that none of them are "poor design" and that "dull" isn't a significant negative for reference material. – Adrian McCarthy Apr 12 at 20:52

10 Answers 10

81

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.

| improve this answer | |
  • 57
    The sites might look "old" is because they ARE old: gcc, binutils, and *nix man pages have been around for decades. If it works, why fix it? As you rightly point out, this is what works for people like me. Another reason might be is that the content in those pages is automatically converted to HTML from source that might be in LaTeX or (in the case of man pages) nroff format. – jamesqf Apr 12 at 3:06
  • 1
    Also, some of these links are linked to generated HTML from manpages or infopages. – Joshua Apr 12 at 4:12
  • 10
    @jamesqf - Not only do man pages work, some of the more modern documentation formats are actually inferior IMHO (I'm looking at you javadoc). I especially appreciate the example/synopsis section showing the user how to use the function/command. This is often missing in more modern documentation. I'm glad that a lot of newer projects especially ones on github have copied the style and spirit of man pages for basic documentation (mostly because documentation need to work with markdown but people are also using man-style argument definitions) – slebetman Apr 12 at 15:09
  • 2
    @Joshua: Not exactly from Info pages; GNU project docs are maintained in Texinfo markdown which can be built into HTML, PDF, and locally browseable info. en.wikipedia.org/wiki/Texinfo. Wikipedia mentions that makeinfo --html tries to be compatible with as many browsers as possible, and the current format is nice and clean so probably not many people are keen to change it. – Peter Cordes Apr 12 at 15:10
  • 2
    e.g. GCC docs have table of contents, an index of keywords to ctrl+f search in without needing any server-side stuff or Javascript so docs can just be dumped onto a dumb web server, and an index of cmdline opts. Also, simple clean layouts get indexed easily by Google, and it's easy to link to a specific page or item in a page via a unique URL that even has a meaningful name. e.g. gcc.gnu.org/onlinedocs/gcc/…. Also loads way faster than the clunky docs like infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0068b/… ARM asm – Peter Cordes Apr 12 at 15:18
39

I'm unable to post this as a comment to one of the other answers due to low reputation, but 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).

| improve this answer | |
  • 21
    ReadTheDocs is an example where "user friendliness" overflows and gets in the way of the users. See e.g. this issue. Had it been designed in the "old dull" format, there'd be no such problem. Regarding JavaScript, there's a tendency for various websites to be unusable without it (i.e. either not rendered at all), or extremely slow with it (I've seen both of these problems on the Internet). If some documentation is presented in such a way, it's useless or at least hard to use for quite some would-be users. – Ruslan Apr 12 at 8:11
24

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.

| improve this answer | |
  • 7
    WRT color coding (which I personally detest), you over look the common flaw of the clueless developer who hardcodes text to black or dark blue, but leaves the background color to be inherited from the system, which is REALLY irritating to those of us who prefer a black background. – jamesqf Apr 12 at 3:10
  • 3
    @jamesqf Oh, there's plenty of ways to mess up any kind of syntax highlighting. This isn't meant as any kind of comprehensive treatise on any of this stuff. – l0b0 Apr 12 at 3:14
12

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.

| improve this answer | |
11

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.

| improve this answer | |
  • 1
    This is probably the most important reason: Most of that software is open source. So it was created by people in their free time. They are not going to hire someone to improve the UI and usually are not interested in doing it themselves since they are not interested and experienced in that – Felix B. Apr 13 at 14:47
  • 3
    @FelixB. Furthermore, they are not interested in it at all, in general, in a very fundamental way, a disdain which I share. Saying "I have no time" is a polite way of conferring "I don't care", as anybody knows who has ever been refused a date. – Peter - Reinstate Monica Apr 13 at 14:56
  • I don't think there is more to it than actually not wanting to spend time on it. I mean you have probably seen documentation of this style a couple of times by now: docs.readthedocs.io/en/stable. Well because it is a template which saves time. – Felix B. Apr 13 at 15:19
  • Ha! Good point. The only conceivable objection to the presentation of stroustrup.com/bs_faq.html is that if you are on a large screen, you'll likely want to take the trouble to reduce your browser window width to something around 850px. Reading really long horizontal lines is horrible. – David Apr 14 at 20:03
8

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.

| improve this answer | |
6

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.

| improve this answer | |
6

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.

| improve this answer | |
  • but... but... but... they'll miss out on the user experience – JCRM Apr 12 at 22:30
  • 4
    @JCRM: I'd pay extra for that feature :-) – jamesqf Apr 13 at 17:20
4

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.

| improve this answer | |
2

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'.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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