Re: Making scripts with sawfish-client

On Mon, 17 Apr 2006 10:57:14 +1000, Geoff Kuenning <geoff cs hmc edu> wrote:

I don't think it's particularly inviting to outsiders if we get
defensive about perfectly reasonable questions and criticisms.

Sure, I agree. I just don't think the criticisms were perfectly reasonable the way they were presented. I welcome constructive criticism. That means being specific about what you think is wrong, how you propose it should be fixed, and the rationale behind it.

I've offered the OP as many specific suggestions and I can think of. If he can provide us with more detailed information I'm sure we can do better. Nobody is getting paid here, you know. The burden lies as much with those seeking support as with those giving it.

The reality is that sawfish, like many (or most) open-source projects,
could benefit from quite a bit more documentation.  The UI to the
window manager itself is reasonably well covered by the texinfo
manual.  But the stuff in librep is discussed only in documentation
strings.  That brings up the classic elisp problem: doc strings tend
to be terse, and you often can't even find out that a function exists
unless you already have a good guess as to its name.
As the original poster said:

In our case, what we need is a clear documentation about how to use the
tools. That means tutorials and howto, and not an API list (that will be
maybe useful, but later).

That stuff doesn't exist at all.  If it _did_ exist, sawfish would be
much more widely used.  How successful do you think Python would be if
there was nothing except a brief listing of library functions with
2-line descriptions?

If I gave the impression that sawfish/librep doesn't need any more docs that I'm sorry. Yes absolutely it could benefit from more and better docs. Almost any project could.

I can't think of too many topics to write HOWTOs or guides on though. Here's one:

	- sawfish and/or librep event loop. how it works,
        how it integrates with GTK, and how to hook in to it.

It's reasonable to respond that nobody has written anything and nobody
has volunteered to do so.  But it's counterproductive to claim that
nothing needs to be written, or to suggest that the solution to such
problems is to make everybody figure it out themselves.

I merely suggested that it doesn't appear to be *that* big of a problem, judging from the lack of questions on the subject and the surplus of working code written for sawfish.

I believe questions relating to the OP's original task should be easily answered by the existing documentation.

If anyone has good ideas for guides/tutorials/HOWTOs please post them here AND add them to the wiki so they're not forgotten about. I've added a "Documentation Wanted" section to the Doc page on the wiki:


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]