Hi, all. [email protected] (2009-02-11 at 2332.24 +0100): > I just put up an inital user-doc. > ... > Is this structure O.K.?
Many elements are involved in sawfish doc. Don't care much about the structure for now, it's too early to mind it. But it's very good to have this kind of doc, and to keep it developing, even if slowly. Yes, this is what I've been hoping for. The relevant things for sawfish doc are covered in length in my post on 10 Feb, "Re: [IMPORTANT] Docs decision"; if you take doc issue seriously and can spare time, could you read it? And give your comments? I believe it provides good starting point. On sectioning. Well, it's very bad to number sections manually. Section numbers will change. Some auto way has to be adopted, after more explicit policy are agreed at. So they can be forgotten to avoid unnecessary hassle. Not only the structure, but writing styles can also be loose as early attempts. For one thing, it's better to have introductory materials on the wiki, like how sawfish differs from other WMs, Why? Suppose, an user is thinking of trying a new WM. They collect info on the web. But the doc in the tarball can't be read until they actually download and open it. Furthermore, having duplicates both in tarball and wiki makes the maintenance difficult, so before the release, unified policy for distributed doc and wiki are desired. One more apparent thing which needs consideration is Capital-letter-files - AUTHORS, BUGS, INSTALL... They're outdated, lacking consistency. Anyway, migration and merge can be done later, and there's no reason to stop developing 'user-doc.info'. First let us gather materials therein. On Thu, 12 Feb 2009 23:49:48 +0100, GSR - FR wrote: > Depends, what is the real purpose of the user doc? Documentation for > users that do not want to get into the guts of Sawfish? Emacs has two infos: emacs and elisp. The former tells basic use, and the latter lisp only. Such kind of separation fits for sawfish, too. # To be more precise. Currently, separate texinfo files are there: # faq.texi, news.texi and sawfish.texi. But they're combined when # output. Such kind of 'partial separation' makes sense. > Then you should cover the concepts, probably starting with what is a > wm or even x11... At end, explain how to get more from other places > or handle small scripts (for the case of "paste this in your rc"). Why not? Or rather, tips like "paste this in your rc" should be available to users. Quickstart is necessary, in addition. As we saw in this message, sawfish doc issue is difficult to handle. This is the reason I said above that slack way is allowed now. And gradual discussion seems to suffice for the time being. We have so many things to do with higher priority, and when the time comes, then we should concentrate on doc. Teika (Teika kazura)
