Make the development docs more blatent about growl HOT 12 CLOSED

Here's the email I sent to the list on 2009-03-18.
---

In the past few weeks, we've received a number of code patches, which is good.

Their authors submitted them as plain diffs against Growl 1.1.4, which is bad.

Don't get me wrong: I'm happy to take a patch as a plain diff against 1.1.4. 
Given the choice between a 1.1.4 
diff and no patch at all, I'll take the 1.1.4 diff.

But I suspected that this may be symptomatic of something: It's too hard to 
find out how we really want a 
patch.

With this thought in mind, I went to our website to see how a patch contributor 
might go through it.

---
Right off the bat, I'm stopped by the lack of any front-page link for code 
contributors. We have a bunch of 
links in no particular order, and nothing that stands out as being of interest 
to the code contributor.

The closest thing, if I look in the right spot, is a link titled “Source”. 
I haven't written my patch yet because I 
do need (ideally the current) source code. However, since this is under the 
large link for “Download Growl 
1.1.4”, I assume that this link would give me the 1.1.4 source. I'd prefer to 
work with the current development 
source, so I keep looking.

First, I try “Documentation”. Buried at the bottom, I see a section for 
developers, with a link to “Developer 
docs”. That sounds like what I need.

Blah, blah, blah… “Implementing Growl in Cocoa Appli…”. Oh. Those kind 
of developers.

(Note: The page does have a link to our page on cloning one of our 
repositories—it's just way down at the 
bottom, and doesn't fit with everything else on this page.)

Next I try Contact. I suppose I'll need to contact us about my patch 
eventually, right? And maybe I can ask 
where to get the source code.

Well, no luck here. Just some RSS feeds, as far as I can tell (assuming I'm not 
familiar with hgweb or 
Bitbucket). At least I found how to email us.

Next I try About. A product summary of Growl, with a link at the bottom to the 
same developer documentation 
I already found and dismissed.

Well, I guess I'll go back to the front page and download the source for 1.1.4.

Huh. Sure are a lot of links on this page that isn't the 1.1.4 source code. Oh 
well—one of the links is to the 
1.1.4 source code, so I'm satisfied at this point.

(The paragraph at the bottom says “Information regarding our hg repositories 
and other areas of interest are 
addressed in the Developer Documentation.”, but that's fine print compared to 
the nice, big download links.)
---

So, I'm right. It is too hard to find out how we want a patch.

We actually do have the page I went looking for:

    http://growl.info/documentation/developer/growl-source-install.php

But I didn't find it in my role-play exercise. Test failure.

## Problem #1: The header links

To start, I'm thinking we should reorder them according to groups:

    Download
    About, Documentation, Screenshots
    Applications, Styles
    Forums, Contact
    Donate

Next we can see about cutting them. The Screenshots gallery can be part of (or 
linked from) About. Forums 
can be part of Contact.

That makes room for a Contribute link.

## Problem #2: No page specifically for contributors

Actually, there is one: The Growl Contributor Handbook. We hadn't linked to it 
because it was a draft; I've just 
taken the draft tag off and made some more edits (most significant: removing 
the Bitbucket stuff, which is too 
heavy an investment for the one-time or infrequent contributor, and adding info 
about not using release 
source and how to get an archive of tip). So now we can link to it from 
somewhere.

## Problem #3: Conflations

There are several pages that seem to be doing multiple jobs. Usually, they do 
one job well and another job 
poorly.

As I mentioned, the Source page is one example. It has links to:

1. The SDK (Huh? That's not source!)
2. An example display plug-in project (Also not source code to Growl, though it 
is technically source code)
3. An example AppleScript script (Not even Objective-C)
4. The Growl source code

Another page doing multiple jobs is the Developer Documentation page, which 
mostly addresses one 
definition of the word “Developer” (app developers) but also contains one 
paragraph for another definition 
(contributors).

We should be clearer about whom each page is for, write and rewrite those pages 
specifically for that 
audience only, and move anything that doesn't belong to another page or a new 
page.

In the specific case of the Source page, we can just cut it, as the Developer 
Downloads page has the same 
content better-presented. The Source link should go directly to the tarball. We 
may want to move the sample 
display plug-in to somewhere in the display plug-in archive, but that's 
low-priority.

As for the Developer Documentation, we can remove the link to the Mercurial 
page from that page, since the 
Growl Contributor Handbook has much of the same info.

Speaking of the Mercurial page (the one I should have found), we should merge 
its contents into the Growl 
Developer/Contributor Handbooks:

- Requirements: Definitely.
- Getting the source: Not much here worth keeping. In particular, it recommends 
the source tarball over the 
Mercurial repo. I don't think people will read to the repo instructions, if 
they even find this page.
- Compiling … Growl: Do we really need this? Do we really want people who 
can't identify an Xcode project 
and figure out how to build it contributing patches?
- … Installing Growl: Maybe worth keeping. Then again, who can write Cocoa 
code but not hand-install a 
prefpane?

As for the Mercurial Installation How-to: Mostly good, but one doesn't need to 
add /usr/local/bin oneself 
anymore. It's in PATH by default as of 10.5.6 (maybe earlier). The Handbooks 
have instructions on installation, 
and we can supplement these with the links to MacPorts, Fink, and the hg Book. 
Then we can cut the separate 
page.

## What should have happened

I arrive at the front page. I scan the list of links in the header and see one 
that says “Contribute”. Well, this 
could mean either code or money, and I want to contribute code, so let's try 
it. (Besides, there's another link 
that says “Donate”, so that must be the one for contributing money.)

“Growl Contributor Handbook”. This seems to provide me with the information 
I'll need to contribute the 
patch. I read it, make my awesome patch, and send it in.

----

Any thoughts? Any other problems that you can see? (Aside from the known 
problem of lots of old info on the 
site.)

We should have things fixed before 1.3

Since we're going to change the framework up in 2.0, this is now a blocker on 
2.0. Development docs need to be... really good.

I'm going to change documentation around so that it is very apparent up front 
as to what topics to click on. When a person clicks on "Documentation" it'll 
come up with 2 or 3 columns, one for end users, one for developers, and 
possibly one other just depending on the content. I may split off and make one 
more section called "Help" and one for documentation that sort of intertwines, 
but that's the general plan.

This isn't going to be entirely solved within the 1.3 release time frame, 
although it's going to be started on. Moving to 1.3.1

I think I've done what I can to resolve this issue on the website. File 
specific tickets on separate items to improve things as we go, or just ping me 
directly.