Page MenuHomePhabricator

Update styling and layout of auto generated docs to fit within main documentation site
Closed, ResolvedPublic

Description

The auto-generated docs (i.e. https://docs.enlightenment.org/auto/) are far harder to read than the main documentation (https://www.enlightenment.org/docs/) - we should make this consistent.
By adopting the layout/style of the docs pages we will vastly increase readability of snippets as well.

The style of the auto/ page could certainly be improved, but the layout is probably far more important to achieve readability. As I see it there are several things to do:

  1. Categorization. Organize the links into a few (2-4) sensible groupings. For example, perhaps one group of high level "outward facing" components that EFL app developers would want to know, from lower level or more internal components, and then a third "misc" category for utilities, tools, and stuff that doesn't fit. Or, another approach could be to split "Core" functionality into one category, with secondary or specialized information in a second.
  1. Group descriptions. Like on /docs/ include a short paragraph per category or group, explaining what the group covers.
  1. Organize link lists from easy to advanced. Assume a novice user will read from top to bottom, so make the first couple items be the ones with the best "intro" level material. Put more specialized or complex stuff at the end of each category's list.
  1. De-jargonify. Assume reader will have no knowledge of EFL or other less known acronyms or names. "freedesktop.org (xdg)" should be phrased "cross-desktop" or "desktop agnostic". "Eolian: an EO file parser..." should be "Eolian: a generic object file parser..."
  1. Reverse the names/description. E.g. instead of "[Eldbus]: D-Bus integration", it could be "D-Bus integration with [Eldbus]". Novices will come to the docs with topical needs in mind, without knowing which EFL component they need, so starting each line with the topic of interest will allow easier eye-scanning.

One difference with /docs/ from /auto/ is that the former includes a variety of accessory links beyond just code docs, including general tutorials, primers, code style guides, etc. which makes /docs/ feel a bit more holistic and friendly. Obviously, /auto/ should not be a copy of /docs/, so those links probably don't fit, but perhaps there are some links that do make sense for including on /auto/, that are of a more general nature? If nothing else, a link to /docs/ from /auto/ couldn't hurt.

ajwillia.ms added a comment.EditedOct 31 2017, 11:03 AM

With just a small diff (

) we can make it look a lot more "in keeping" (
) - it would be a good start don't you think?

Starting with embedding and styling, then I will look into some of the structural changes for presentation especially on the home page.

With just a small diff

Going for something even simpler - styling the text but using an embed to get the usual frame and navigation set up.

OK, this is getting somewhere:

ajwillia.ms closed this task as Resolved.Nov 3 2017, 11:25 AM

Embedding now avoids the need for a layout change as it looks the same to the user.
I updated the huge list to be a little more readable and I think we're good to go.