 |
|
|
|
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Saul Luizaga wrote:
> Haskell I presume?...
More specifically, every open source project I've ever been hired to look
into that was intentionally designed to be extended or embedded by the end
user. None of them (besides Tcl) has ever had any documentation on how
you're supposed to use the libraries. Applications, sure. Something that
only programmers see? Why the hell would we need any *prose* for that?
--
Darren New, San Diego CA, USA (PST)
There's no CD like OCD, there's no CD I knoooow!
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
"Darren New" <dne### [at] san rrcom> wrote in message
news:49d699b2$1@news.povray.org...
| 50,000 files, 370 meg of code, "developer" web pages like "here's how
we
| capitalize our identifiers and where to put spaces", and "here's how
we plan
| to modify the way we do unit tests", and not a single "this is what
the fuck
| each of the 14 top level directories hold, let alone the other 1500
directories.
|
| It's hard to believe that wikipedia is more informative about what the
open
| source project does than the wiki for the open source project itself.
|
So, contribute to the open source projects.
You like to see the kind of documentation you want, write it.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
pan wrote:
> So, contribute to the open source projects.
Well, duh! Why else would I be trying to find documentation on how the
source code is organized and where to find various classes and interfaces?
> You like to see the kind of documentation you want, write it.
That attitude is exactly the *cause* of the problem. By the time I have
learned enough to be able to write that documentation, it's no longer a
benefit to me to write the documentation. That's *exactly* the way in which
this sort of open source fails.
However, it's pretty trivial to write that sort of documentation if you're
the original author of the code, and takes far less time than actually
writing the code or deciding what it should do or how it should be organized.
--
Darren New, San Diego CA, USA (PST)
There's no CD like OCD, there's no CD I knoooow!
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Darren New wrote:
> Saul Luizaga wrote:
>> Haskell I presume?...
>
> More specifically, every open source project I've ever been hired to
> look into that was intentionally designed to be extended or embedded by
> the end user. None of them (besides Tcl) has ever had any documentation
> on how you're supposed to use the libraries. Applications, sure.
> Something that only programmers see? Why the hell would we need any
> *prose* for that?
>
I see. Is there a council or .org that regulates open source projects
structure that this kind of projects can base their work on? Or at least
it should be, somewhere they can reference and get their projects in a
more formal and understandable form.
If not, I think someone would think about it.
Cheers.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Darren New <dne### [at] sanrrcom> wrote:
> 50,000 files, 370 meg of code, "developer" web pages like "here's how we
> capitalize our identifiers and where to put spaces", and "here's how we plan
> to modify the way we do unit tests", and not a single "this is what the fuck
> each of the 14 top level directories hold, let alone the other 1500 directories.
Judging from thedailywtf.com, proprietary code isn't always much better
either.
--
- Warp
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Warp wrote:
> Judging from thedailywtf.com, proprietary code isn't always much better
> either.
Especially CAD software - excluding the huge sellers like AutoCAD.
They're actually quite powerful programs, but the documentation is
incredibly poor, and often incorrect. I remember the docs of a certain
EM simulation software giving an example of how to calculate something
that made no sense physically. And the _proper_ way to calculate it was
not in the docs.
--
It's not hard to meet expenses, they're everywhere.
/\ /\ /\ /
/ \/ \ u e e n / \/ a w a z
>>>>>>mue### [at] nawazorg<<<<<<
anl
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Saul Luizaga <sau### [at] netscapenet> wrote:
> Darren New wrote:
> > Saul Luizaga wrote:
> >> Haskell I presume?...
> >
> > More specifically, every open source project I've ever been hired to
> > look into that was intentionally designed to be extended or embedded by
> > the end user. None of them (besides Tcl) has ever had any documentation
> > on how you're supposed to use the libraries. Applications, sure.
> > Something that only programmers see? Why the hell would we need any
> > *prose* for that?
> >
> I see. Is there a council or .org that regulates open source projects
> structure that this kind of projects can base their work on? Or at least
> it should be, somewhere they can reference and get their projects in a
> more formal and understandable form.
>
> If not, I think someone would think about it.
Yeah, everyone is waiting for that rather than just digging into the code and
getting the hands dirty. :)
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Warp <war### [at] tagpovrayorg> wrote:
> Darren New <dne### [at] sanrrcom> wrote:
> > 50,000 files, 370 meg of code, "developer" web pages like "here's how we
> > capitalize our identifiers and where to put spaces", and "here's how we plan
> > to modify the way we do unit tests", and not a single "this is what the fuck
> > each of the 14 top level directories hold, let alone the other 1500 directories.
>
> Judging from thedailywtf.com, proprietary code isn't always much better
> either.
5+ Insightful
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Saul Luizaga wrote:
> I see. Is there a council or .org that regulates open source projects
I think it's more that open source authors are writing code for themselves.
They don't need to document it, because they know what it does. The next
person coming along can't document it because they *don't* know what it
does. By the time that next person understands well enough to document it,
*they* don't need to document it. All of which slows down the adoption of
that particular piece of open source.
I've come to learn that if your project has a wiki, it probably means "we
have no documentation, and we're hoping the users will supply it." A few
notable exceptions, sure, but not many.
Actually, I think that's a good question for the next person I interview for
a commercial position: "Have you added functionality to any open source
project?" Yes. "Show me the documentation you wrote for programmers who
come after you." Ooops. No wonder software is so unreliable.
It's not like programmers don't know how to document stuff. They just don't
feel the need to, because it's no benefit to *them*, since they're giving
the code away for free and don't really care whether someone else can use it.
--
Darren New, San Diego CA, USA (PST)
There's no CD like OCD, there's no CD I knoooow!
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Warp wrote:
> Judging from thedailywtf.com, proprietary code isn't always much better
> either.
Quite true, but for different reasons. :-)
--
Darren New, San Diego CA, USA (PST)
There's no CD like OCD, there's no CD I knoooow!
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
