Re: [NEWS] inital user-doc in svn

[Teika Kazura <teika lavabit com>]

Hi, all.

zanghar freenet de (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)