Do we need a documentation application?

[Mike Danko]

This is the best news I've heard in ages. As a user, the disconnect between Fedora docs and system docs has been difficult to grasp. The use-ability of both is difficult to impossible to grasp, especially when you bring up the point that we've adapted docs to applications instead of vice-versa for so long. Menu item? Hit F1? Read a man page? Why should the behavior of an application dictate where I go to learn about it? Why are there separate libraries (in the literal sense) of docs on my system?

Is it time to progress past the separate paths of windows 3.1 "hit F1" mentality, the manpage mentality, and the "if I hover here, maybe I'll get a tooltip" paradigm? To me, this is an obvious answer. 

As a group, we have the know-how to have a unified support system. If this isn't the use case for docbook, I don't know what is. It would be a definite shift for folks used to a linear path for writing, but one well deserved for consumers. 

I suppose the rest of the discussion boils down to user stories. How would both your grandmother and your cryptogeek friends be best served by such scenarios? How do decide what is contextual documentation and what isn't? How do you best present contextual documentation in a unified manner. 

Most if not all of the answers will find their place upstream, but I'd think its about time to at the very least question the behavior so the engineering decisions can have a basis. 

- Mike
-----Original Message-----
From: "John J. McDonough" <wb8rcr at arrl.net>
Sender: docs-bounces at lists.fedoraproject.org
Date: Sun, 03 Apr 2011 11:09:29 
To: <docs at lists.fedoraproject.org>
Reply-To: wb8rcr at arrl.net, For participants of the Documentation Project
	<docs at lists.fedoraproject.org>
Subject: Do we need a documentation application?

In GNOME 3 the whole concept of menus is gone.  This means, among other
things, that there is no Documentation menu.  There are a number of
categories:

  Accessories
  Games
  Graphics
  Internet
  Office
  Others
  Sound & Video
  System Tools

There is also an 'All' category, but this only includes applications
that are in one of the other categories.  An application must be
specifically placed in the 'Other' category to appear there.

I could see putting the Release Notes in "System Tools", but it doesn't
seem to me that documentation in general belongs there.  Yelp is in
"Accessories", but that category is already cluttered, and I can see
"System Tools" getting pretty cluttered, too.

To further complicate the matter, previously GNOME, XFCE and LXDE could
all share a .desktop file.  It looks as if now a unique file will be
required for GNOME.

Were we to have some sort of Documentation application we could then
have something like update-desktop-database that would run on install.
This would allow us to have single-language RPMs and still maintain
consistent Fedora-like language behavior.  I can't say I'm really
thrilled with this, but it is an alternative.

Another alternative would be to go back to installing a separate set of
documentation for Yelp, and let it deal with all the GNOME weirdness.
Or, perhaps we can press shaunm to get Yelp working smoothly for html
documentation.  I have to admit I haven't played much with Yelp on
Fedora 15, and I know there has been substantial work done.

--McD


-- 
docs mailing list
docs at lists.fedoraproject.org
To unsubscribe: 
https://admin.fedoraproject.org/mailman/listinfo/docs