Page MenuHomePhabricator

Analyse Tizen EFL documentation
Closed, ResolvedPublic

Description

As per the documentation IRC meeting on 20171020, analyse the Tizen EFL documentation for information on how to improve the Enlightenment EFL documentation (and other E-related documentation in the future.)

Related Objects

Created an overlay designed to offer insight into the layout and approach taken by the Tizen EFL documentation team:

ghalfacree added a comment.EditedOct 23 2017, 6:36 AM

Initial analysis published to the efl-technical-documentation mailing list, reproduced below for posterity.

Key features of the Tizen EFL documentation, which are worth calling out as why people may prefer it over the proper EFL documentation:

  1. Complete navigation visible at all times on the left-hand side, with expandable sections. You can never get lost!
  2. Single-column view: clear, responsive.
  3. Tiny font. TINY. But it's black on white, and still pretty easy to read.
  4. Dependencies are called out in a box right at the start of each doc.
  5. Verbose, but friendly.
  6. Next/Prev navigation buttons at the bottom.

    Contrasting with the current proper EFL documentation:
  7. No easy navigation available from a document, other than going back to where you were before or following a link from within the document itself. Easy to get lost.
  8. Front page is triple-column, making it cluttered and hard to read - especially in a narrow window.
  9. Larger font, which is nicer, but grey-on-grey, which isn't.
  10. No nice box at the top telling you exactly what you need to have already done before starting.
  11. Often terse, sometimes feeling more like an aide de memoire for existing devs than a guide for newcomers.
  12. No handy-dandy navigation.

Added information gleaned from the Tizen approach to the draft Style Guide. Appropriate section reproduced below:

As discussed on the efl-technical-documentation mailing list and IRC channel, the priority for the documentation project is to overhaul any and all documentation required by a third-party developer looking to build upon the Enlightenment Foundation Libraries (EFL). These documents should, where possible, be modelled after the Tizen Developers EFL documentation. This means:

  • *No cold opens* - All pages must include the title and an introduction, the latter being one or two paragraphs which explain the purpose of the documentation in plain English with no assumption of prior knowledge nor requirement that the reader have any idea what they are doing.
  • *All terminology marked out* - If a document contains a technical term, whether exclusive to the EFL or not, this term must be highlighted using \*term\* Markdown syntax for its first use. If the precise meaning of an item of terminology is not explained immediately following such marking in the document body, it should be placed after the term itself and before the close of the sentence in brackets.
  • *Expand all acronyms and initialisms* - If a document contains an acronym or initialism, such as EFL, it should be first introduced highlighted in its expanded form followed by the commonly-accepted abbreviation in brackets (so "*Enlightenment Foundation Library (EFL)*.") This is true even for terms the reader should be expected to know (like EFL).
  • *Use paragraphs* - No single paragraph should be longer than four or five sentences. Treat a paragraph as a place to introduce a single concept, and once that concept has been introduced move on to a new paragraph before introducing another or expanding upon what you've written.
  • *Use subheads* - Split the document up into as many sub-sections as makes sense. This is especially important for documents where it's likely a reader may want to skip ahead for reference, as we can also use subheads as navigational anchors.
  • *Don't be afraid to split documents* - Just because something is addressed in a single document in the current format doesn't mean it should stay that way in the revamped version. If it makes sense to split an existing document into two or more new documents for clarity, do so.

An important aspect of the Tizen documentation is the navigability, which stands in stark contrast to complaints of the EFL documentation that it's easy to get lost and difficult to find things.

As a result, I'd recommend the following structural changes to the website as part of the documentation overhaul:

  • Add a permanently-present boxout to the top of all documents with the dependencies, contents arranged by headings, and links to related documentation.
  • Add a permanently-present contents list for all documentation to the left-hand side of the documentation site, with collapsible sections.
  • Add 'Prev/Next' links as a footer to all documentation pages.

This is something that would need to be done within the documentation platform itself; I'll open a second ticket so it can be discussed separately and, if agreed, its progress tracked.

ghalfacree added a comment.EditedOct 23 2017, 8:14 AM

Added the following to the Style Guide:

  • *Don't hide content* - Current EFL documentation includes heavy use of a 'folding' plugin for DokuWiki, which hides contents until it is clicked upon. When encountered, this should be replaced with extreme prejudice: hidden content is anathema to good accessibility. Make sure that all contents of a document is visible as soon as it is opened without manual interaction; if this makes the document unwieldy, consider splitting it into multiple smaller documents as above.
pbrown66 added a subscriber: pbrown66.EditedOct 24 2017, 1:15 PM

Making the case for a change in style

@cedric asked me to look for data that would support in a push to change the current colors and layout of the website. I had already read up on accessibility and readability for another assignment and reached my own conclusions.

However, to try and avoid bias I used neutral search terms like "best color combinations for readability" and avoided weighted terms like "tell me why using gray for the color of a font sucks". I also bypassed anecdotal evidence and went for guidelines supported by reputed organizations or backed by research.

Here are the results:

Text/Background Contrast Ratio

According to the W3C Accessibility Guidelines, contrast between foreground and background must be at least 4.5:1

The color of the current font is #818181 and the background is #303030. You can check for yourself the contrast ratio and see if it is up to code.

SPOILER ALERT: It isn't. At 3.39:1, it is too low.

For accessible reading, that is, for people vision impairment, an even higher contrast of 7:1 is required.

As explained by the W3C:

People with low vision often have difficulty reading text that does not contrast with its background. This can be exacerbated if the person has a color vision deficiency that lowers the contrast even further. Providing a minimum luminance contrast ratio between the text and its background can make the text more readable even if the person does not see the full range of colors. It also works for the rare individuals who see no color.

Color Combinations

Both dark text on a light background and vice-versa would satisfy the contrast criteria, but which one is better is controversial. According to one random person on the Internet(TM):

Black text on a white background yields the best legibility, since the bright glow from the background causes your pupils to contract. It's easier to focus your eye with a smaller pupil (much like the depth of field is increased with a smaller camera lens), and it reduces the effect of refractive errors in the eye.

I have been unable to find any scientific evidence to back up this claim, however.

What I have found is a study that, through a series of tests carried out on 136 subject, tried to determine the readability of combinations of colors for texts and backgrounds:

The tl/dr is that subjects scored higher when reading black text on a white background than any other combinations of colors. They also rated the other factors, such as retention of the information gleaned from the text and the perceived "professionality" of the pages according the different combination of colors. Again, black on white came out on top in both cases.

There doesn't seem to be any scientific data that contradicts these conclusions, and there is plenty of anecdotal evidence that supports them.

Links

The links make it difficult to tell whether they have been clicked on or not, as visited links look very similar in color to unvisited links. There is also a slight glow around the links that makes them harder to read. Jakob Nielsen has quite a lot to to say on how to implement usable links.

Conclusion

Research suggests that the current combination of colors used on the site is far from ideal and should be changed to make it more readable and accessible.

By changing the contrast ratio of the text over the background and the colors of both, as well as the behavior of the links, you will effectively be overhauling the whole look of the site. It seems there will be little point in holding on to the current layout, which may have suited the old combination of colors, but will probably look at odds with a new color scheme. Besides, if you follow sound accessibility and readability guidelines, the new site will look so different from the current one that a change in layout will be the least noticeable thing.

ghalfacree closed this task as Resolved.Oct 30 2017, 9:11 AM

Completed and discussed on the mailing list and IRC, with conclusions inserted into the documentation guide for later publication.