What does “Human Readable” mean? Is it a misnomer?

Question

Two examples spring to mind:

• One of the reasons that .Net programmers are encouraged to use .config files instead of the Windows Registry is that .config files are XML and therefore human-readable.

• Similarly, JSON is sometimes considered human-readable compared with a proprietary format.

Are human-readable formats actually readable by humans? In the example of configuration data:

1. The format doesn't change the underlying meaning of the information - in both cases, the data represents the same thing.
2. Both registry and .config file are stored internally as a series 0s and 1s. To that extent, the underlying representaion is equally unreadable by humans.
3. Both registry and .config file require a tool to read, format and display those 0s and 1s and convert them into a format that humans can read. In the case of configuration stored in the Windows Registry, this is a Registry Editor. In the case of XML it could be a text editor or XML reader. Either way, the tool makes the data readable, not the data format.

So, what is the difference between human-readable data formats and non-human-readable formats?

Answer 1

Human readable basically means that if the content is displayed by a program that lacks direct, specific awareness of that file's format, that there's at least a reasonable chance that a person can read and understand at least some of it.

Your basic point about the lack of a clear line of delineation is absolutely correct though --at one time I knew a guy who could diagnose problems with programs (mostly written in Fortran) often in five minutes or less -- going only from an octal core dump, without looking at the source code at all. For most people, that format would hardly qualify as "human readable", but obviously he was an exception...

Answer 2

Human Readable means I can open the thing in Notepad if I want to, and change "password=foo" to "password=bar" if I so desire. I don't have to use a proprietary tool to look at or edit the content.

Contrast to a PDF which you cannot edit with a simple text editor - you need a specific tool that knows the format. Or a binary .dat file that came with some application from 25 years ago that you can't read, edit, or understand.

Answer 3

In response to your question "Are human-readable formats actually readable by humans", by definition yes they are, that's what human readable means.

There isn't a technical definition of human readable, it's subjective and there might be questions about what level of knowledge the human might need to have to qualify (for instance do they need to understand the very basic principals of XML such as tags and hierarchies, should they understand the business domain the data exists in - personally I'd say yes to both) but your basic test should be if I showed it to someone with basic technical skills who understood the basics of what the data was meant to represent it, can they read it.

On a practical level this will generally mean the following:

1) The data is stored as ASCII text or some other similarly common and easily recognisable format

2) That there is a reasonable structure that is self evident from a basic examination. For instance you don't have to know that the first X characters related to Y, then the next X relate to Z

3) That both the data and the meta data generally are in English (or whatever your local language is) and require only limited knowledge of the problem domain to understand - so an invoice number would be in an "invoiceNumber" tag, rather than "uDef_Inbr"

4) For non-text data sensible, predictable conventions have been used (for instance TRUE, FALSE, Y, N, 1, 0 rather than something more open to interpretation)

Answer 4

.config files are much easier to edit (for most people) than the Registry. It's easier to open a dedicated config file, find the relevant data, and make changes without opening the possibility of editing something that will affect other programs.

Answer 5

It's all about ease of understanding (and likely changing). So "Is X human readable?" shouldn't be answered with a "yes" or a "no". Rather, the answer should be along some sort of sliding scale.

Potential examples:

• 90% of programmers could read and change the file with any common text editor.
• 60% of English speakers could read the file with any common text editor.
• 80% of XYZ developers could read and change the file, but only using tool ZYX.
• 10% of YZX developers could read and change this file with a common text editor.

Outside of a context that explains what "human readable" really means, the phrase doesn't help all that much. (Some human somewhere can probably read any of the formats, if you don't count trying to look at the magnetic polarity of the hardware bits themselves...)

Answer 6

One big difference between human-readable formats and non-human-readable formats is robustness. In a Linux system, all sorts of information will be scattered around in various text files. You do need to learn where they are, but you can always find the information and read and change it with a text editor. If a file disappears, you can generally replace it. If a file becomes corrupt, you can often figure out what it should be and fix it.

In a MS Windows system, most of this will be in the Registry, which is, from the users' point of view, one big opaque system, accessible in part through various tools (much like some config files in Linux systems), and overall with a registry editor. As long as everything goes well, this is okay. If it breaks, there's nothing that can be done without specialist knowledge.

Answer 7

The easiest checks I can think of that qualify as "human readable" is:

• in a location/file that can be easily accessed by external editors (this would make the registry not "human readable")
• doesn't use non-displayable characters in the data structure. If I make an Office 2000 Word doc with the text "test" inside, I might be able to open that in notepad and find the 4 characters "test" somewhere inside, but there will be a whole lot of other stuff around it.
• While not required, formats that contain descriptive metadata are a plus. A file that contains JohnSmith|34|T|F is less friendly than <User><Name>JohnSmith</Name><id>34</id><isActive>T</isActive><isAdmin>F</isAdmin></User>, as know what the fields are (at least generally) in the 2nd.

Answer 8

I think you may be asking whether "human-readable" as a term is sometimes incorrectly applied, and no-doubt it is. In the example of registry entries vs .config files, I think it helps that you can arrange the XML in different ways depending on the data, intersperse comments and so on.

Collections in .config files are generally handled as multiple elements, while it's more difficult in the registry, often as as a MULTI_SZ.

You can also see more of the configuration data for an application at once - with regedit, to see something that is in a different key you need to navigate to that key, which means you can no longer see the entries you were previously looking at. With .config files, you can see the entire file at once, even though that file may contain hierarchical data.

Answer 9

Contrast "human readable" with binary. For example, you can't generally open an executable or a database index in an vanilla text editor and understand what the content is. The bytes below decimal 32 don't even have globally standard representations as visible characters.

Answer 10

Short answer: It means the information is entered as text, rather than binary or hex, etc. Something that equates with a readable "language" rather than a computer "machine language". Beyond that, the definition gets murky.

Answer 11

It also applies to code - you structure your program in a logical and thoughtful manner such that the job of anyone looking at it for the first time is made a bit easier.