![](/i/fill.gif) |
![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
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
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
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
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
Invisible <voi### [at] dev null> 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
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
>> 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
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
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
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
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
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
>> 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.
Heh. Yeah, it does seem that way sometimes...
Post a reply to this message
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
nemesis wrote:
> Well, now you can boast the thing in the Haskell mailing lists and see if they
> continue mocking you. :)
They will.
Post a reply to this message
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
Invisible wrote:
> 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.)
Well, if you're shooting for a technical writing position, this
accomplishment becomes highly relevant.
Regards,
John
Post a reply to this message
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
John VanSickle wrote:
> Well, if you're shooting for a technical writing position, this
> accomplishment becomes highly relevant.
Agreed.
--
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*
Post a reply to this message
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |
|
![](/i/fill.gif) |
| ![](/i/fill.gif) |
|
![](/i/fill.gif) |