Yes, it is. git pull/push to gmic-community, markdown, gmd2html
for previewing. gitk
, (the git GTK repository browser), seems to be the essential tools here. All of these substantially reduce the logistics of posting documentation and seeing what other contributors are doing. Kudo’s to @David_Tschumperle and whoever helped him.
That leads to the writing.
Every FOSS project lacks documentation. To my mind, it is the single greatest barrier to FOSS adoption. If people don’t understand how to use it, they won’t use it. Period. Full stop. Faster to buy a license to a commercial product and call the support line, look at the slick videos they’ve prepared. Maybe (!) read the user manual.
I think everybody is a born writer. But eighty percent of us develop a permanent writer’s block. Sets in after the age of seven or eight, I think. Fifteen percent of us can manage tweets, maybe email. Five percent can hit the ground running.
I’m a professional writer. But I’m not in that five percent. Most days, I feel awful when I start to write. Words don’t come. There’s a barrier I have to get over. Once I’m over it, I’m fine. How to get over that barrier? How do I get over that barrier?
A very long time ago, my technical writing mentor suggested that I close my eyes and imagine someone sitting across from me. I just need to explain something to that person, that’s all. Imagining writing as a kind of conversation with another person has always helped getting over that barrier.
In that line, I like to think that I need to tell that person three things about a gmic command:
(1) An essential summary that covers what the command does. I imagine that the person may be suddenly called away with the phone or a baby crying (!!! can’t ignore that!). So if they get the gist of the command, that is something accomplished.
(2) Then (if the person is still with me), a few examples of how the command is used.
a. Usually one example that is straightforward,
b. One that is a little more complicated, but serving a ‘real world’ purpose,
c. And one - if possible! - that uses the command in a novel, unexpected way: it has an ‘Ah HA!’ twist. If nothing else, people find plot-twists amusing.
(3) Then, the command reference.
That’s my outline, (1), (2), (3). That’s how I’m (re) organizing these tutorials in the present round. You’ll see that Summary-Example-Command reference template throughout. Having that template also organizes my thinking, so I can imagine what I need to say to that imaginary person, so I can imagine myself saying that to the imaginary person. So writing is just transcribing that inner voice talking to the imaginary person.
In the flow of writing, (3) is much easier than (2), (2) is usually easier than (1), and (1) is hard. Recall the famous apology: “I’m sorry I wrote you a long letter. I did not have time to write you a short one.”
Distillation is always hard. Distillation is what happens from (2) to (1). David has made (3) trivial: just write the inclusion markdown for a command and you have exactly what gmic -h
supplies. Perhaps write a few helpful notes after the inclusion. (2) arises from just playing/experimenting with the command. Seeing examples here at pixls.us/gmic is always useful. Everybody: please post more! Playing and experimenting is the fun part of tutorial experience. At its conclusion, it is a matter of choosing the best examples and writing those up. Then there is the gist of the command; (1). I save that to the last. I find that if I’ve played a lot during (2), (1) becomes easier to write.
As you may have gathered, I write these tutorials backwards: (3) - study the reference (2) - play with the command. Then try doing useful things. Then trying for that "ah HA!’ moment. Then organizing my thoughts for (1).
So you have trouble starting to write. I feel that pain. But there is this: I’m almost 70 (!). As a project planner once quipped to me: “In the long run, we’re all dead.” Funny. Ha, Ha. But in the heart of that bittersweet joke there is this truth: If we care about this thing, we got to tell the people coming on board how to play with it. How to work with it.
While we still can.