Do we need a documentation application?

[Eric H. Christensen]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On Sun, Apr 03, 2011 at 06:02:38PM +0000, Mike Danko wrote:
> 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?

Well, I guess the easiest answer is that we can't plan on where everyone is expecting to find help.  What doesn't make sense is moving the location where people can find solutions every release.  There should be a standard location where you know that you'll find answers.  Man pages work well in this way as people know exactly where to go get answers for CLI programs.  F1 works for GUI programs.  Where do you go to find answers that don't fit into those categories?  Well, docs.fp.o is one place.  Another should be somewhere on your computer so you don't *have* to have Internet connectivity when you have a question.

> 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. 

DocBook has a pretty big overhead for just displaying the help from man pages.  Man pages are easy to ship because there isn't a lot of overhead compared to the actual data.  There is quite a bit of overhead in DocBook.
 
> 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. 

I used to like the place we had carved out under the "System" menu.  It was our own little dumping ground and people knew that's where they could find help (if they installed the package, which is another topic all on its own).  But since that is gone we have to go back to the drawing board and figure out our new standard.
 
> 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. 
> 
Well, right now upstream is not giving us answers and if anything is just creating new problems for us (read that to mean "moving target").  I agree that we should go with upstream solutions but sometimes we have to provide those solutions to upstream for inclusion.  Fedora is somewhat unique in that most distros don't have documentation, outside of application help, in their OSs so this generally isn't a problem.  We may be the only people to find/suggest a solution for upsteam uses.

> - Mike

- --Eric
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)

iF4EAREIAAYFAk2Yu6cACgkQU03aaJDMNEX/8gD/YLTXittYpIrXPXcz34++rkKH
NHeRJWaGVq9XcmT0m2wA/jEd4hcdEnsbiLywfJ2hWhuAF7niBQ9ruhfqmt/ocFXx
=717G
-----END PGP SIGNATURE-----