Re: [IMPORTANT] Docs decision

[Teika Kazura <teika lavabit com>]

Hi all. I posted a short version, too. This is a long version on docs.

Let me clarify the issue in this post, as a starting point for the
discussion. 'Doc' implies many things. The summary is given at the end.

First of all, we already have the texinfo manual of sawfish. (I'll refer
to it as 'least-doc' hereafter.) The minimal goal for doc in 1.5.0 is
to ask that least-doc contains all updates for sawfish-1.5.0. It's an
extension of the existing doc, keeping the current style & structure. 
I'd say it is the sole realistic goal. The reason will be clear later.

Because of our limited human resource and the difficulty of the
required work, it is very important to set the clear goal, decided by
the priority. Is it OK to think this 'minimal goal' precedes any
other?

In fact, we may be able to get a bit further then the least one by
1.5.0.  Putting the least-doc aside for a while, let us think what
other kinds of docs are like:

* Capital letter filenames in the source tarball: AUTHORS, BUGS,... 
  They also need be updated and arranged.
* Wiki.
* Rep intro. As a lisp intro (for Janek?). Timo has given a short
  comparison of rep and other lisps.[1]
* Quickstart.
* Configurator GUI manual. (I confess that I don't understand items
  like auto-gravity and depth. I tried them years ago, and failed to
  guess the meaning.)
* Basics of WM for users. Can be part of least-doc or configurator GUI
  doc. Separation of easier and more advanced parts may be
  better. Example of the latter is event system. (I picked up this
  example from wiki. I don't know how much it is important, because I
  don't know WM basics.)
* Librep maunal completion. (Many sections lack.)
* How to write C code.
* Comments in C & lisp source.
* Howto. Tips. FAQ. (The current faq is unsatisfactory and partly
  obsolete)
* List of bugs, wishes ...
* release procedure manual & checklist (?)

[1] http://mail.gnome.org/archives/sawfish-list/2008-September/msg00023html

Who said overwhelming? Don't get intimidated. You'll have noticed
several points.

1. Because sawfish is programmable, the boundary between user doc and
dev doc is vague. But quickstart is absolutely a user doc, and C
manual is dev.

User manuals are *musts* for sawfish to be exist as a public being. It
will serve to invite new users. (I'm going to write a manifesto on the
importance of the newcomers. Or would you?)

On the other hand, dev doc & info will strengthen the understanding of
sawfish of dedicated users, or more exactly, will provide the base of
developments. It is a sad fact that they lack. (In my opinion,
preparing dev info first is surer, though seemingly roundabout.)

2. Appropriate media, formats, styles vary for each.
* Some have definite forms when completed, e.g. quickstart,
  configurator doc. Some are not, or rather, never finish: bug & wish
  list.
* With-form ones are composed as a project, but shapeless docs are
  not always. Latter can grow from daily activities. (See 3 below.)
* Shapeless docs are easier to maintain in wiki than to be in svn
  trunk. It depends for the others.
* Dev docs can be loose, like tips, especially in early stages. It is
  better to have exact one, though.

3. Howto, tips, or faq are 'mother doc'. 
* They can contain every kind of pieces of information.
* They can be thought as a collection of raw materials for other docs.

I'd like to ask you (and to myself :P) to be conscious that tips item
seeds are everywhere, arise anytime you use sawfish. Writing down
* New things you have known or noticed,
  or things you remembered that you had a struggle with before,
* Strange feeling with some aspect of sawfish,
* Questions,
then a mere collection of them can be called tips, and classification
makes it already an easy but real doc.

I'd also like to remind you that often mysteries and things you want
to know are common. So just putting the question in public space can
result in a big return to the community, once someone answers it.

Currently you can give away such info at
http://sawfish.wikia.com/wiki/Tips
Don't be afraid to clutter that page. Having any to open is better
than nothing. (I renamed it from "Developer's tips". Not only to 
developers.)

4. Terminology, i.e. the technological word definition and usage, is
not part of a doc. In fact, it is the premise of all docs, but it can
only be revised in the process of writing/revision of docs, codes and
specification of the sawfish. (I assume that we're aware terminology
needs re-examination.)


Now let us turn to general aspects of doc compilation.

Janek Kozicki wrote:
> Just fill in the missing parts ... is a *very* hard work anyway.

Yes. Documentation is a intellectual work involving experience,
observation and sophistication. Furthermore, completion of a doc
requires thorough study in that field. It requires one person or more
to work regularly and continously, and is really tough.

I think 'doc, bug, todo & wish party' is unavoidable in near
future. Without in-face confrontation to the issue, it is hard to
proceed. It will also make us feel sure what is the right
direction. Lack of perspective (and doc) is too often the weak point
of open source development.

Doc party will take long to complete. Because of the amount of the
supposed achivement in 1.5.0, I don't think the release of 1.5.0 have
to wait for the doc project. So, documented sawfish can be the goal of
1.6.0.

Finally after the long excursion, let us get back to the 'least-doc'.
What is its currest status? You may know that Derek Upham had done a
great contribution (by himself!). According to him[2], all C api are
up to date. Lisp part is partial, but his list of coverage is precise,
so we can figure out the rest.

[2] http://home.avvanta.com/~sand/sawfish/

However, there's a pitfall: updates between 1.3 and 1.5.0.1 are not
complete. Derek's update in last September[3] only covers maximazation
across xinerama.

[3] http://mail.gnome.org/archives/sawfish-list/2008-September/msg00067html

I think that's all to be cared for the least-doc.


For file format. I'm also for keeping least-doc in texinfo, by the
same reason as others. One more reason is that emacs info is good,
provided that enhanced to suit your needs. (Not good enough at all,
but far better than others.;)

But configurator GUI manual naturally needs image, so html sounds
usual.

I don't have any idea for tutorial, quickstart, etc. If something like
svn manual[4] can be generated from some kind of source, it's good,
but I don't know what it is like.

[4] http://svnbook.red-bean.com/en/1.5/index.html

Mark Diekhans said:
> It would be realy nice to not bring any more dependencies for using
> sawfish.
Touché, yet it is possible to distribute compiled form, requiring
users nothing.


On doc structure, Christopher Bratusek wrote:
> structure example:
> > 1.0 Basic functions
> > 1.1 Iconify

I think we're too early to think of it. Anyway, it'll be better to ask
authors to propose the prototype, and discuss based on it.

Let me ask you one thing: to keep the discussion lucid, could you keep
your answer in this thread only regarding the general issue? Fire
another thread for each specific subject, terminology, source
comments, etc. I think this is a modest proposal.

When we get stuck, let us try to summarize. Write, and you understand
far better. And when we reach an agreement, loose or good. ML is so
oblivious, and not easy to read for those who didn't participate to
the discussion. (Suppose you leave for a vacation.) Currently, the
best place to collect the summary is:
http://sawfish.wikia.com/wiki/General_todos

Summary:
1. Least-doc goal is OK?
2. Doc party for 1.6.0?
3. Please contribute to tips!

Some odds & ends.

There're many pages on the web written about sawfish. It must be easy
to search for them outside of English. (I know there're many in
Japanese.) Pages written by users are constructed the stuff they want
to know in center, so a very good suggestion for doc writers, even if
outdated.

Doc authors will notice plenty. They will churn out great tips.

A short history will be lovely.

Regards,
Teika kazura