Reflecting on FeedbackPublished on 2015-02-23
While at last month's Cambridge Hackfest, members of the GNOME Documentation Project team talked with Cosimo Cecchi of Endless Mobile about the user help in their product. As it turns out, they are shipping a modified version of Yelp, the GNOME help browser, along with modified versions of our own Mallard-based user help.
Knowing that they were actually shipping our help, we wanted to get a closer look at what they were doing, and wanted to get some feedback as to how things were working for them.
- In terms of modifying the appearance of our help, their technical writers found it difficult to modify the CSS that we use. Cosimo noted that the CSS for our help is not stored in a single file, nor even a single directory -it's partly embedded in Yelp's XSLT.
While not always ideal, there are reasons for this. For example, if a person's visual impairment requires that they use GNOME's High Contrast GTK theme, Yelp will pick up the theme change and will use a corresponding color scheme when it renders the help for that user. Similarly, if a user sets their default system language to a Right-to-Left-based language (such as Arabic), Yelp will also pick up that change, and will display the help in the appropriate Right-to-Left manner automatically.
These are both useful features, but it is good to get feedback on this. Creating a custom documentation "look" is important for a downstream distributor, so there's room for us to improve here.
- The technical writing team at Endless Mobile customized the HTML output to feature broadly-grouped sections as html-buttons along the left-hand side of the help. I wish I had gotten a screenshot of this, because we were impressed with how they grouped and formatted the help. This may be an approach that we look to use in the future.
I talked with Cosimo about incorporating some of their updates into our help, and he was very receptive to it. While we'll mostly be focusing on content-related updates for our 3.16 release, we'll consider how we can improve our help based on their feedback in the future.