I heard of that Clutter

dunhillmartin — Mon, 23 Jan 2012 03:44:26 -0600

I heard of that Clutter ideas, yet as others said you need to be motivated when you try this.

Clutter is very vast indeed.

Ted — Tue, 06 Sep 2011 09:46:15 -0500

Clutter is very vast indeed. You can't learn it in just a snap. But I'm glad that you share your clutter experiences. As a reader, it gives me motivation to understand the API more. I'm kinda tired of doing home based data entry jobs so I decided to learn how to develop. This is a good start.

Writing the Clutter cookbook

elliot — Wed, 01 Sep 2010 17:32:32 -0500

I'm almost exclusively working on the Clutter cookbook at the moment, and I keep meaning to write about what it's like to spend your time writing. I'm not sure what's driving this need to explain myself. I think it's partly because I feel a bit unproductive at times, despite working pretty hard, and I feel like I need to understand why.

Perhaps if I explain the pattern of my work week. It goes something like this:

Start the week thinking about which part of the Clutter API to write about. Clutter is pretty vast (well, not the API so much as what it makes possible) and flexible (so you have choices about how to implement a particular feature, animation, effect, UI element etc.). I am still finding stuff in there I haven't noticed before: new functions, configuration options I haven't noticed, whole new chunks of API (it's evolving like nobody's business). But at least I put together a plan with the Clutter maintainer, Emmanuele a while back, which puts some structure and priority around which things which are important.
I then try to come up with a recipe idea to illustrate part of the API, or an interesting topic, or to answer a question I've noticed on the mailing lists or IRC channel. The idea might be something like "reusing an animation with different UI elements", or "handling mouse button presses", something like that. I may also look around at other treatments of the same thing in other cookbooks, tutorials etc., on the web and in O'Reilly Safari; perhaps even try to find videos of a particular UI effect (e.g. today I was looking at cover flow videos, implementations, patent applications [can I even write about that kind of effect?]).
Then I try to write some example code to get a feel for the API. This might involve talking to the Clutter developers on IRC about how something works, or maybe sending something to the mailing list. Occasionally I find bugs and log them (this can suck up a lot of time as I try to do as much due diligence as possible before logging anything, and provide decent reproducible test cases if possible). I frequently need to write maybe half a dozen small programs and perhaps a small application to try stuff out (like: "what happens if I put this UI element over this one?", "how does the height of an element get reported if it's moved away from the view point (into the z axis)?", "If I set this property, how does that affect the object's behaviour in this context?" and so on).
(The code I'm writing is in C, which I admit is a bit of a struggle. I'm just about getting to grips with it now.)
At the same time as I'm writing this code, I'm maintaining my own git branches for each recipe I write, as they have to be kept isolated from each so they can easily be merged in one at a time (hopefully). This means keeping up to date with Clutter as it's being developed. So I'm also learning git (which I've never used a lot before) to pull changes in from Clutter master to my branches (and still sometimes screw it up).
While I'm doing that, I'm also starting to think about this part of the API from a developer perspective: Are there alternative ways to do this in Clutter? Why should I use this approach? Why not this other approach? I start putting notes together about the code I'm writing, very rough to start with.
At this point, I quite often find myself paralysed as I start writing the text for the recipe. Writing text is much harder than writing code, at least for me; particularly writing text about code. (I can write code until the cows come home, but writing text is much harder: which is why most open source projects have lots of code and very little, mostly poor documentation.) Sometimes, finding a decent "story" to tell about the recipe or piece of code can be frustratingly hard (like what I've experienced today when approaching ClutterAnimator :) ), and I find myself suffering what you might call "writer's block". At which point I make several false starts, write free-form pieces trying to articulate what I'm doing, what I'm explaining, just write anything at all to try to shift the block. Sometimes I can be blocked like this for half a day; frustrating, unproductive, prevaricating, maddening half of a day. Sometimes the best thing to do is take a break, go for a walk, do some admin or research on something else altogether. Then before I know it, thankfully, the next day everything slots into place again, and I can write again.
At some point while I'm putting tangible paragraphs together in my rough draft, I move it over to the Docbook template for the cookbook. This means putting XML mark-up and formatting around what I've written so far. This then gets checked in with the code; edits are then checked in as I go along; occasionally I'll merge edits together (thankyou, git rebase -i) to make the development history less convoluted.
I also take any screenshots and video (the latter using gtk-recordMyDesktop) I need and incorporate those into the XML template.
Eventually, I get something together and end up with a first draft. Then I leave it for at least half a day before I go through it again, cleaning up the text and making sure my branch is spick and span.
The process of iterating over the recipe to improve the text is something miraculous to me: I don't do it consciously, but somehow I can read text and rewrite it to read better. I don't know how I do it, to be honest. Which is good, because it means I've basically turned the skill into a habit; but that in turn makes it difficult to reflect on. I don't think I could teach it to anyone either, as I don't explicitly understand the unconscious rules I'm applying.
Finally, I submit the recipe as a bug to the Clutter bugzilla. I typically post a bug marked as an enhancement request (e.g. http://bugzilla.clutter-project.org/show_bug.cgi?id=2288), along with a link to my git branch (e.g. http://gitorious.org/clutter-cookbook/clutter-cookbook/commits/cookbook-...). At this point, Emmanuele may come back to me with some requests for changes or comment on the bug; I try to respond as quickly as possible, and put a note on the bug when I'm done. At which point, hopefully, Emmanuele merges the work into Clutter master and the recipe is complete.
In an average week, I can turn out one or two recipes. If I'm trying to write an introduction to some Clutter concept (e.g. last week I was writing an introduction to ClutterScript), it might be slower, as I have to understand the scope of the concept and find a way to communicate it.

It's the blockages which frustrate and shame me. I wish they didn't happen (they are pretty depressing too), but I think they might actually be an essential part of the "creative process". The miracle of copy-editing makes up for it :).

townx - Writing the Clutter cookbook - Comments

I heard of that Clutter

Clutter is very vast indeed.

Writing the Clutter cookbook