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
