On Thu, Jan 13, 2005 at 03:34:24AM +0100, Uwe Stöhr wrote: > John Weiss wrote: > > >Doesn't follow a structured concept, eh? > >Maybe you should read the mailling list archives before insulting me. > > Sorry I wouldn't harm anybody. I didn't know that there is an active doc > maintainer. I asked that on the docs- list a year ago and nobody replied. > Are you the current doc maintainer?
Sure, go ahead and be snide. I suppose I deserve it... No, Uwe, there's no one actively maintaining the docs. There hasn't been for a few years now. But that could be for two reasons: (1) I and my helpers did our jobs right 7 years ago and came up with something which, while scratched and dinged up in places, is still servicable. Or (2) I didn't do my job right and the docs are so bad-off as to be useless, yet the User community is afraid to take on the daunting task of writing new ones. I don't subscribe to the LyX user's list (too much traffic, and I have enough trouble keeping up with the devel & docs lists these days), so I'm not hearing the howls of pain caused by the existing docs that you seem to be. > I missed a structured concept in that way, that I often have to search > in all three parts, the UserGuide, Customization and Extended for > keywords to find the information. For a normal user it is often not > clear what is extended or what might be in the UserGuide. - Partly, this is semantics. You should've seen the Great Naming Debate that went on for "User Guide" and "Extended". <bleh> Boils down, again, to having an international user base who put slightly different connotations on English words depending on what they translate them to in their heads. You are not now, nor ever will fix that, Uwe. - Partly, its changes introduced to the "Introduction.lyx" manual. (I don't remember it being as long as what I see right now, just having looked. I also remember trying to keep it to a bare minimum, as I expected "Introduction" to be the frequently-accessed first-point-of-contact, not a one-off throwaway, which it's been turned into. The whole "Philosophy of LyX" stuff belongs in either the UG or the Tutorial, not in Intro) - Mainly, though, it's due to a failing in my vision: The Reference was supposed to be the "search for j-random-feature, find which docs cover it" index you seem to be missing. Reference was supposed to be a community-wide maintenance effort. It wouldn't be pretty, but it'd be thorough. I even included a sample, "Here's how to add an entry," section in the thing. But nooooo... no one bothered to start there. No. Too busy painting the house to bother replacing the rotting clapboards they're trying to paint over... > >Not all of the menus are described because one doesn't need to know > >what they all are. > > But that's the intention of a UserGuide! Now you're being unfair by taking what I said out of context. You do not need to know what they all are all at once in order to use LyX as an effective writing tool. You do not need faxing in order to write a paper, and playing around with character formats is a Great Time Black Hole, one regularly used to avoid doing the real work: writing the content. > Another example: After three years using LyX, I now found out what the > menu Navigate->Bookmarks does and how I can change the number of > available bookmarks. This feature is very useful for me, but wasn't > described in the docs. 1. Was added in the past year or so. We've had no docteam in that time. 2. Useful, yes. Necessary, no. You don't need a navigation tool to figure out what you want to say in the regular flow of text, and what you want to put in a bullet list. Which is rather the whole point of LyX: forget the exterior frills. Focus on the content. (Read at bottom for some related gripes (not at you).) The User's Guide was supposed to contain only those features that give you the advantage of focussing on content over appearance. (<sigh> But I said that before, several times, and you ignored me, several times. Why should now be any different...) > As you can see undescribed menus won't be used. > > >>and ironic comments. (These comments are often funny but > >>shouldn't be part of a manual.) > > > >...because manuals should be as dry as dust, and so boring that nobody > >looks at them? > > Yes of course ;-) I mean commands like "If you use Export->PostScript > you can start drinking a coffee" (translated from the german docs). If > users don't laugh about it, it scares them off. That's poor translation. Read the original English. Which, now that I think of it, may be a bit dated considering modern processor speed. > Nobody read a UserGuide from the beginning to the end. Except of the > tutorial, docs are used as reference book. Because most of them are as dry as dust, boring, and treat the reader like a lobotomized mentally-disabled-person. > I've already done adding some of the customization stuff to the > UserGuide. In my opinion sections like the one describing the > preferences should be in the UserGuide. Again, this doesn't fit the main purpose of the UG: Writing. Tweaking your settings is a different ball-o-wax. (And a great way of avoiding doing the real work of writing.) > >Right now, I have doubts. I read a lot of high-flying ideas from you, > >with very little grounding in practicality. Let me give you an > >example of what I mean by "practicality": The "Customize the X > >keyboard for non-US-English". We added that because the lists were > >getting about 2-3 "Heeeelp Meeeee" messages a month asking for this > >information. There was a practical reason for adding it to the docs, > >so in it went. > > Describing additional things like setup X-issues will hamper it keeping > the docs up to date. Things changes so fast - especially every Linux > distribution is different. Therefore I want to get rid of it. You missed the point. I'm not even trying to justify keeping X-keyboard-stuff in the docs. I'm using it as an example *why* something would go into the docs. Use your user audience to guide what needs to be explained more thoroughly. For instance... > As you mentioned the lyx-users list, you should browse it through the > last years to have an impression about actual problems. There are almost > the same questions: > > - Why does the font look pixeld in the pdf-output. > - Formula issues > - encodings (unicode) > - bibtex issues DING!DING!DING!DING!DING! You win a prize! This is what I'm talking about. What do the users find "works" in the docs as-is, and what do they find lacking? > >There were practical reasons for the division of the docs. > > I've never said, that I want to merge them all together. Sorry. My Bad. I was getting that impression from your initial emails on the subject. Just remember: documentation, like software itself, has design criteria, be they explicitly stated, or implied. It's good to be explicit. > I introduced LyX to my institute and also to elder people - mostly > Win-users. The last time I send 50 mails per month to the users-list > answering questions. So you can believe me that my intention is to > introduce things that are "broad-user-community-consensus-based". Then you are DaMan for the job. > And now let us please discuss at a normal level. Okee Dokee Then. Let me give you a bit of historical perspective: While there have been many opensource projects in the Deep Past, they all treated documentation as the ugly bastard stepsister, if they bothered with it at all. But now, it's not at all uncommon to see both a Development Team and a Documentation Project on OpenSource software web pages. Credit for this must go to KDE. See, when Matthias Ettrich started KDE, one of the things he did was start a Documentation Project to go with it. This way, anyone can contribute, not just programmers. Now, where do you think Matthias got the idea for a Documentation Project? >From his previous project: LyX. Take a wild guess who started the LyX Documentation Project. I say that not with boasting, but with pride. Everytime I see a major OpenSource project with a link on its web page to a Documentation Project, I smile. See, when I was Editor-In-Chief of the LyX DocProject, I got told one that I'd make a good manager. I let the contributors write how they wanted, as long as they kept to the (1) Notation; (2) general doc-design; and (3) overall doc-style. Or so I was told. When someone strayed too far, I tried to gently steer them back. Or so I was told. When they strayed only slightly, I'd just do cleanup myself. Yet I'm also a developer as well as a documenter. I have a foot in both worlds, so to speak. So, I'm not just spouting idle opinion. I know of what I speak. I'm just being lazy and not explaining myself. :) And now, some pet peeves of mine to explain my perspective: <rant> Why the heck is repeating the mistakes of the past so trendy these days?!? Like, take whitespace. Some people seem to think that making whitespace a syntactic part of a programming language will make that language magically "more readable" somehow. But we had syntactic whitespace back in the 70's and threw it out as a Bad Idea. Not only that, but it didn't make code any more readable back in the 70's either. Why the hell do they think it'll do so now? Or take manuals. They're boring and written for idiots. Yet we all know that the real problem is cluelessness, not stupidity. So we end up with manuals that insult the reader's intelligence, bore the reader into not wanting to go further than page 3, and then, injury atop insult, only provide the most superficial of overviews of features whose purpose is already self-evident from their names. </rant> Common pet peeves. -- John Weiss
