I found a minor glitch. I reported it on the bug tracker. It got 
partially fixed. But then it sat there waiting.

I downloaded the source code. I compiled it. I modified it. I checked 
it. I created a patch, and I submitted it. And, on Thursday, my patch 
was committed to both the STABLE and HEAD branches.

Woo, me! :-D

Now I can write on my CV that I have "contributed to an open source 
project".



Uh... OK, I admit it. It was a documentation glitch. I wrote a few 
paragraphs of documentation. I never actually touched any source code. 
(Although I _did_ read through it to find the information required to 
write the documentation.)

And, immediately after Igloo committed my patch, he committed a second 
patch that further modifies my text. (In particular, the undocumented 
feature I just documented has been changed slightly in HEAD - which I 
didn't notice until *after* I submitted the damn patch!)

So... yeah, not actually as impressive as it sounds at first, eh? :-/

Post a reply to this message

On 3/2/2009 4:34 AM, Invisible wrote:
> So... yeah, not actually as impressive as it sounds at first, eh? :-/

Are you KIDDING me?  You just did something that 99% of open source 
programmers are totally and completely incapable of doing!

Great job!

-- 
...Chambers
www.pacificwebguy.com

Post a reply to this message

>> So... yeah, not actually as impressive as it sounds at first, eh? :-/
> 
> Are you KIDDING me?  You just did something that 99% of open source 
> programmers are totally and completely incapable of doing!

Er, how do you figure that? If you're an "open source programmer" then, 
by definition, you must spent time programming OSS. (Which, technically, 
would be more than I just did. All I did was write a paragraph or two of 
documentation...)

> Great job!

Heh, thanks.



In truth, all I actually did was describe what one of the Haskell 
compiler switches does. (It makes a compiled Haskell program dump a 
terse description of how it was compiled.) The compiler manual already 
said the flag was there; I just wrote a few words about what the dumped 
data is supposed to mean, based mainly on dumping some data and using 
common sense. (But also leafing through the source code a little so I 
could look at the comments.)

Post a reply to this message

Invisible wrote:
> would be more than I just did. All I did was write a paragraph or two of 
> documentation...)

Most open source documentation sucks. You wouldn't believe how often I've 
seen open source documentation that says "We don't know what this does, 
cause the guy who wrote it won't tell anyone."

> (But also leafing through the source code a little so I 
> could look at the comments.)

Because having a dump of informative data with no interpretation available 
is at all useful, right?  Don't put yourself down - you even noticed it 
needed to be fixed.

-- 
   Darren New, San Diego CA, USA (PST)
   My fortune cookie said, "You will soon be
   unable to read this, even at arm's length."

Post a reply to this message

Darren New wrote:
> Invisible wrote:
>> would be more than I just did. All I did was write a paragraph or two 
>> of documentation...)
> 
> Most open source documentation sucks. You wouldn't believe how often 
> I've seen open source documentation that says "We don't know what this 
> does, cause the guy who wrote it won't tell anyone."

Heh. Yeah, nice.

GHC falls somewhere in the middle of the scale. The documentation is far 
better than a lot of OSS projects. What it covers, it covers reasonably 
thoroughly. On the other hand, it's not exactly stellar.

GHC supports a huge number of weird and wonderful "extensions" to the 
official Haskell language, almost all of which have extremely terse 
documentation. You might argue that it's not a compiler manual's job to 
teach you how to program in Haskell. OTOH, since these are GHC-specific 
extensions, where *else* are you going to document them?

>> (But also leafing through the source code a little so I could look at 
>> the comments.)
> 
> Because having a dump of informative data with no interpretation 
> available is at all useful, right?  Don't put yourself down - you even 
> noticed it needed to be fixed.

Heh, yeah.

Of course, since the major consumer of this information is going to be 
Cabal, which is mostly developed by the same team of developers as GHC 
itself, it isn't that big a deal. Also... well, take a look at this:

  [("GHC RTS", "Yes")
  ,("GHC version", "6.10.1")
  ,("RTS way", "rts_thr")
  ,("Host platform", "i386-unknown-mingw32")
  ,("Build platform", "i386-unknown-mingw32")
  ,("Target platform", "i386-unknown-mingw32")
  ,("Compiler unregisterised", "NO")
  ,("Tables next to code", "YES")
  ]

I documented what this means. Most of it you can actually guess (and, in 
fact, I *did* guess). Only a few things really "needed" explaination.

OTOH, I added that explaination. (Which the committer than immediately 
edited again anyway.) I guess that's something. ;-)

Post a reply to this message

On Mon, 02 Mar 2009 07:24:31 -0800, Chambers wrote:

> On 3/2/2009 4:34 AM, Invisible wrote:
>> So... yeah, not actually as impressive as it sounds at first, eh? :-/
> 
> Are you KIDDING me?  You just did something that 99% of open source
> programmers are totally and completely incapable of doing!
> 
> Great job!

Seconded.  We need more people writing documentation for some of these 
projects. :-)

Jim

Post a reply to this message

Invisible <voi### [at] devnull> wrote:
> Uh... OK, I admit it. It was a documentation glitch. I wrote a few
> paragraphs of documentation. I never actually touched any source code.
> (Although I _did_ read through it to find the information required to
> write the documentation.)
>
> And, immediately after Igloo committed my patch, he committed a second
> patch that further modifies my text. (In particular, the undocumented
> feature I just documented has been changed slightly in HEAD - which I
> didn't notice until *after* I submitted the damn patch!)
>
> So... yeah, not actually as impressive as it sounds at first, eh? :-/

Well, now you can boast the thing in the Haskell mailing lists and see if they
continue mocking you. :)

Post a reply to this message

>> Great job!
> 
> Seconded.  We need more people writing documentation for some of these 
> projects. :-)

Heh. Reading through the mailing lists, I'm seeing a common pattern here:

"Hey, I just released library X."
"Neat. Does it support feature Y?"
"Not currently. It shouldn't be too hard to add it though. Patches 
gladly accepted."

See that last sentence? Yeah.

-- 
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*

Post a reply to this message

Invisible wrote:
>>> So... yeah, not actually as impressive as it sounds at first, eh? :-/
>> 
>> Are you KIDDING me?  You just did something that 99% of open source
>> programmers are totally and completely incapable of doing!
> 
> Er, how do you figure that? If you're an "open source programmer" then,
> by definition, you must spent time programming OSS. (Which, technically,
> would be more than I just did. All I did was write a paragraph or two of
> documentation...)

If you're an "open source programmer" then, by definition, you must spent
time programming OSS, and almost no time writing documentation.

Post a reply to this message

On 3/2/2009 8:53 AM, Invisible wrote:
> [("GHC RTS", "Yes")

> I documented what this means. Most of it you can actually guess (and, in
> fact, I *did* guess). Only a few things really "needed" explaination.

I hope the above doesn't mean what I *think* it means... :)

-- 
...Chambers
www.pacificwebguy.com

Post a reply to this message