Hi, L p R n d n <g...@lprndn.info> skribis:
[...] >> I think it’s hard to generalize. What I do like about some GNU manuals >> is that they’re well written and well structured; they can serve both as >> a reference and as a way to get started. Examples of these include the >> libc and the Emacs manuals. These are really book-quality, and are >> actually published as such. > > Just to be clear, I was not talking about the content of the manuals. I'm > in no position to judge their quality. And as you said, some are really good. > I'm giving my opinion about the global layout, shape, css used in most > of their manuals. I find them difficult to read (probably not true if > you're used to them) because of things like contrast, lenght of lines > etc. Without modifying the content, visual hints and helpers can really > enhance the reading experience. Things like a left menu (as proposed by > swedebugia) can be, IMHO, the difference between a read manual and an > unread manual. > WDYT? Oh I agree with you: a better CSS would improve things (note that the ugliest manuals you’ve seen on gnu.org don’t even have a CSS), and a menu and visual hints would certainly help too. >> I understand it’s a very different approach from what people do >> nowadays, which is often more “quick-start” but also short-term-ish, but >> I like the idea of working to help users understand what they’re doing, >> as opposed to just throwing at them the minimum they need to know to get >> things done. It’s about emancipating users, after all. > > I totally agree with you here. The goal must be to empower the user. > But I also think manuals like we have and quickstart/cookbooks are not > opposed but complementary. The latter are here to help people find their > way without being overwhelmed by the quantity of information of a > manual. The former really shines once a user has been introduced to the > subject. > > For example, I think the packaging tutorial written by Pierre Neidhardt > could really find its place in the documention (if the author agrees > obviously). It's a nice *bridge* from guix user to guix hacker. > Probably not in the manual but in a separate part of documentation. > (how we separate them is another question). > That kind of document can make the difference for a newcomer. Maybe you’re right and that’s what I liked about Pierre’s tutorial. The manual also has a “Defining Packages” section with similar goals, and I like the idea of having introductory material like this directly in the manual, but sometimes a separate and informal document can help too. Thanks, Ludo’.
