Page with thoughts on various things...

GNOME Documentation: Thinking Outside the Box

Here I will try to collect ideas for GNOME 3.0 documentation. I will try to look around and see how KDE, Windows and Adobe (since here at the office I have all Adobe stuff installed) are also handling documentation, just to have an idea how they do things.


Why not running a survey for documentation? Phil Bull proposed it way back in the ubuntu-doc mailing list, but it has never been done. It could be done in a "fashionable" way with the help of the communities, both GNOME, Ubuntu and other ones. Something not outsourced, something created inside the community and hosted (if possible) by the community.

It should not be a documentation survey for documentation writers or technical/advanced users, but for end users and possibly translated in as many languages as possible to let non-English speaking people participate. In this case the community should help providing translations from English to their native language and also from their native language to English if there are going to be questions that need a long answer.

Possible wannabe questions:

  • Are you using the help system?
  • If not, why?
    • Is it not accessible?
    • You didn't know about it
    • You didn't find it
  • If not, and you need help, what do you use?
    • forum -> which

    • IRC -> which channels

    • friend
    • other -> specify

  • ...

The Box from Outside

  • How would I like documentation to be?
    (This is personal opinion)
    Useful, short, that gets to the point, that resolves my problems and that explains me how to achieve things, but with an eye also on some more deep thoughts I might have.

  • How is Yelp, the central place for documentation, right now?
  • How would I like it to be?
  • Is Yelp easy to find? Is the Help system easy to reach for users?
    Why is it accessible from the System menu and not from Applications? Usability? In my very own mind, I think it will be more accessible from the Applications menu, if not accessible at least more visible (I remember this was discussed somewhere, but don't remember where and which was the conclusion... or am I imagining it?!?!). Windows help system is accessible from the Start menu and is 'visible', it is not hidden in a submenu, or inside another menu, but Windows has the advantage to have a single menu. What are the plans of GNOME 3.0 with regards to these menus? Are they going to disappear with new methods for launching applications?
    Looks like that if I remove the icon from the top panel, in Ubuntu, a new menu voice is added inside Application -> Accessories. Why not a new voice in the main menu (Applications) instead of a submenu?

  • Would a video tour or some sort of virtual tour of the desktop be useful for users starting to use GNOME?
    Probably this will be more useful by downstream distributions for presenting new applications, what's new in the system, what has changed, where to find new applications and where old ones have moved. Thinking about GNOME 3.0 and the probably radical new UI (at least reading the plans for GnomeShell and Zeitgeist) a features tour would be interesting to both new users and advanced users that are not taking part of the development. Looks like some of the problems with KDE 4.0 started also from a situation like this (I'm basing this on opinions I heard from friends and other people that are "advanced users" and felt lost with the new passage, I personally have never done a switch from 3.x to 4.x with KDE): missing information/documentation on what is new, what has changed from the previous version, where are applications that once used to be there but now are gone... things like that.

  • One License to Rule 'em All
    I'm not talking about using only one license, I'm not very interested in which license as long as it guarantees freedom of use and reuse. Right now, when creating documentation, you have to sort of include a legal.xml file that will automagically be rendered with all revisions history and authors. Would be nice, in a new documentation system, to have a separate file with this kind of information (revisions, authors and translators) plus the system file with the license (that already exists). The documentation system should know where these files are located and if necessary load and render them. In this way it could be possible to have a central place with all documentation history and authors and a link from within the document that show this things to whoever is interested. Right know each document comes with its history/revision/authors/translators history that you can see, the new approach should "hide" this information and present a link. Where should be this link be? Could be a fixed small link in the right upper corner of the window (About this document), or even two link (About this document - License), or at the bottom or even hidden from within the documents themselves: how many end users are reading those information?

Crazy Ideas

  • Use Yelp like a web 2.0 front end for the documentation
    Could be interesting to use WebKit/WebKitGTK and the Javascript features that GNOME 3.0 will have to create something visual appealing to end users, something maybe AJAX-style, to present the documentation. It should be friendly, a11y and i18n compliant, fully keyboard accessible. It should not be a "web 2.0 application" on the desktop, but a desktop application with similarity to a web 2.0 application: dynamic, maybe some dynamic contents that can be localized/customized like an RSS feed with documentation links or with links to support forum for distributions, maybe a small optional IRC pane (using telepathy) which points to a support channel (most useful for distributions).

  • Give Yelp more "colors"
    Right now the "first page" is not very "friendly", Windows help system has graphics and lots of links. Could be interesting to re-think the start page, give it more colors some graphics, I think it needs also to re-think the search result page (screenshots at the bottom).

  • Use Yelp to gather information about what users read
    Could be interesting to use the help system to gather information about what an user reads from the documentation, giving feedback to the doc team about each section of the documentation (like google help does: was this page useful? did these information resolved your problem?). This should be done with the consensus of the user, selecting a check-box and explaining that no personal information will be stored (apart maybe from Yelp/GNOME version and distribution name), but this need an infrastructure on GNOME part where to store information, how to show them and to who.

The Huber Editor

Thoughts about FoieGras and editing that also leads to documentation in general...

  • It should focus on documentation, not translations: translators are happy with PO files, give 'em a PO and they'll conquer the world a language at a time
  • Extensively, Mallard should be convertible to PO files
  • Commit integration: now with git you can't download a single directory, you have to download the entire tree, with all the history of the documentation. Is the casual user/documentor happy with this? How can the integration work in this case? Using some kind of web app like Vertimus for translations where someone enter, see the error, edit the page submit... ? In this way there should be a [Edit] link in the document that takes to the web page where the actual editing will happen. But what about synchronization? How can we synchronize between web and desktop? Right now packages have to be created "manually", an approach like this should, form my POV, re-think packaging also.
  • Wiki style approach: should be easy for new users, as long as there is a WYSIWYG That Works(TM). MoinMoin graphical editor is not an option right now (i think it has been even disabled on this wiki and in many others for obvious reasons). WikiMedia, Drupal or other systems all have a graphical editor, but there's the necessity to store information in Mallard style or at least to export them in Mallard style. The export feature, if thinking in term of wiki style, is not that obvious: why should I export the data? For the desktop help? Shouldn't it better to have a sync automatism with this kind of approach? MoinMoin seems to have something similar for some particular pages (like help pages and the spam page). I think it comes down to how much the documentations storing mechanism will change. In a wiki style approach translations are going to be a little bit a crazy thing to handle: ever tried to translate MoinMoin? Even translating a Drupal content is not straightforward if you don't understand the node structure of Drupal and is easy to mess things up. Windows 7 has new nice feature that, if you want, includes also on-line documentation results for your search or even by default (should be interesting to discover more about this).

Of Help Systems and Others


(This is based on Ubuntu 8.10)


  • Clean interface
  • There are some topics to choose from on the left, probably a little bit more graphics in this case would be appreciate
  • Missing tabbed navigation: probably users are getting used to it with Firefox and other browser
  • A glossary with information technology, desktop and computers terminology would probably be appreciate by users (in the case of a glossary, need to find a good way to alphabetically order it based on translations)


(This is based on Kubuntu 9.04)


  • Resembles the help system from Adobe, at least at the eyes
  • It presents you a lot of links and documents' titles, probably too many: are user going to deal nicely with all that links? Both on the main pane and in the side pane
  • The pages are HTML like, resizing the window is like resizing a browser window with a website made for 1280x1024
  • The "style" of the help is like the TLDP style, looks like reading those kind of documents: very accurate, but too lengthy, wordy. In each document you have at the start authors, revision numbers and all those things. Are user really interested in those kind of things?
  • There is a glossary, some of the terms refers to KDE terminology (Kdeprint, Konqueror, Kdepart) explaining what those terms are for, many terms are computer related
  • One good thing is the Shift+F1 shortcut for accessing the "what is" feature: you can go around and click on UI parts and see a little help-balloon coming up; lots of those UI things don't have an help though

Mac OS X

I don't have one... but planning to borrow an old copy of Leopard from a friend.

Adobe (in Italian)

Full View


Compact View


  • Two different types of interface: a full one and a more compact one without the side pane and all the more advanced features

  • It resembles Windows help center (is it based on it?)
  • The side pane has an interesting Bookmarks (the almost hidden Segnalibri in Italian) tab

Windows XP

I'm using XP since Vista looks like is an Epic Fail(TM) all around the world. Would be interesting to have a copy of the soon(?) to be Windows 7 to see what have been done.


  • Little bit complex interface
  • Interesting is the use of "colors" in the interface: icons that resemble the arguments of some help topics
  • Windows help, when connected to Internet, should show some kind of "live news" about documentation (tested with an Italian version of the help, but nothing appears)
  • The search box and button are bigger and more visible than Yelp

Windows 7

Since it's possible to use a free copy (great marketing, wonder where did they copy from though :) ) until next year, I managed to take tons of screenshots of the help system. Would be nice to see if it changes when the real release of Windows 7 arrives.


  • The interface is pretty clean, but prettier that others: some light colors/gradient, icons that do their work
  • The starting page has very few links and links to the help topics
  • On the "status bar" there is an option for choosing to use on-line help and off-line
  • The "More support options" takes you to a page where you can see others kind of help and where you can find help. There is also a "Ask a volunteer expert" section for Windows community (see screenshot below).


  • The actual help is very simple, topic based
  • There is also the possibility to launch the application you are looking for help
  • Nice "drop-down" style of the help contents


  • When the on-line options is enabled, there's also the possibility to say if the help topic was useful or not


Look for a Needle in a Haystack

What would be nice:

  • integration with desktop indexing and searching system like Tracker
  • good and easy way to search
    • semantic search?
    • semantic documentation?
  • possibility to extend the search through Internet
  • possibility to extend the search through Internet but only within specific resources: distribution wiki, forum, whatever...
  • full text and topic based search



  • Results are just displayed
  • Missing information on the window title: probably something like "Ubuntu Help Center - Results for %s"



  • Results for more advanced users, at least the Adobe suite is intended to people who already know a little bit of computers
  • The interesting part is the Aiuto relativo a selection (roughly translated into Help about) with which is possible to narrow the search only to a specific program of the suite (like Photoshop, InDesign...)

Windows XP


  • I like the difference a lot of words, "tutorial" is a more deep guide, different from the task oriented one, on how to use a a particular program or a deeper analysis of one argument (Internet and web security with IE, IPv6, etc...)
  • If you pick a task or a tutorial, at the end there is also a "related arguments" link that points to similar topics

Windows 7

  • Windows 7 has different search results based on the off-line/on-line switch option



  • Interesting to know is the "View definition" link and pop-up.
  • Some words are highlighted with a different link color: clicking on this shows a small pop-up with a brief explanation of the term




  • With my installation I can search only within man pages, even after building the index, not very useful. Cannot say how the search works.

Brasero doc

An Italian user in a mailing list pointed out that it's not possible to create a real "DVD video", not a DVD full of videos, but like a real DVD with all directories and stuff like that, to play it with DVD-player, starting from a directory with all the necessary stuff. Actually he was trying to create a "Video Project" where instead you should create a "Data Project" with Brasero, but this is not explained in the documentation.

Should be better to add a note about that.

Pictures In Docs



MiloCasagrande/Thoughts (last edited 2009-07-26 19:09:34 by MiloCasagrande)