www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - engineering manager perspective - D suggestions

reply prefetch <prefetch_member pathlink.com> writes:
hi all,

i run a small engineering shop, and i've recently become very interested in D -
mainly because it is so much like C, killer performance, but without the VM, and
all sorts of the nice properties that so many recent language have (like memory
management, etc.)

my background: software engineer, C/C++, some perl and python.

anyway, about 72 hours ago i started on my quest: "let's explore D and see if
it's a good language to use for our next engineering project".

so far, i'm still on the fence.

my number one complaint is about the documentation.  it's HORRIBLE.  i mean,
this language is almost 5 years old, and the basic runtime library doesn't even
have a function index?  and it seems like i'm really lucky if i get a definition
that includes expected return codes.

if this language is ever going to make an impact, it needs some work on the
basic docs.  i think it's great that there are all these library projects going
on, but can someone who knows this language well PLEASE take a few days and make
the docs usable??

most of the last few days i've spent using the archaic search mechanism on the d
site to figure things out, but that's awful because the google search include
all the C++ docs/posts from digital mars - which is a mess to sort through.
also, the web interface to this newsgroup has no search mechanism at all, so
that's no help.

the most recent language i evaluated was python, and it's got fantastic
documentation.  kudos to python!!  why can't D take a few days and bust out some
*good* docs so people like me don't have to pound their heads against a wall to
try and figure out if i'm too dumb to understand the std.thread docs, or if they
are just broken - or when i have to grep for 'sleep' in the phobos 'source' to
figure out if it's available since it isn't documented anywhere.  the list goes
on.  i'm sure i'll figure all this our over the next 72-196 hours, but i think
most people will probably give up and say "D is cool, but it's not ready for
prime time yet" just because of the immaturity of the documentation.

here are two simple suggestions that wouldn't take a couple of experienced D
developer too much time:

-an index of all functions, with links to docs (or at least source)
-a 'complete' phobos reference w/ code snippets

holy crap, i think D is awesome (thank you bright et al!!), but is this asking
for too much?? WTF?
Aug 16 2005
next sibling parent reply =?utf-8?B?RGF3aWQgQ2nEmcW8YXJraWV3aWN6?= <araelx gmail.com> writes:
On Tue, 16 Aug 2005 18:36:19 +0200, prefetch  
<prefetch_member pathlink.com> wrote:

 -an index of all functions, with links to docs (or at least source)
 -a 'complete' phobos reference w/ code snippets

 holy crap, i think D is awesome (thank you bright et al!!), but is this  
 asking
 for too much?? WTF?



I think language is not realy stable right now, so nobody take care of  
writing realy great docs of things that may change soon.

D is awesome right now and will be awesone^2 when it'll reach it's next  
stage. And I bet it will have great docs even sooner. With help of this  
newsgroup, current docs and D sources you can get comfortable right now,  
but I know what you mean.

Just have to wait ... love don't come easy ... it's a game ... oh sorry  
... wrong place.
-- 
Dawid Ciężarkiewicz
Aug 16 2005
parent Dave <Dave_member pathlink.com> writes:
In article <op.svl34ciq58xlqs localhost.localdomain>,
=?utf-8?B?RGF3aWQgQ2nEmcW8YXJraWV3aWN6?= says...

On Tue, 16 Aug 2005 18:36:19 +0200, prefetch  
<prefetch_member pathlink.com> wrote:

 -an index of all functions, with links to docs (or at least source)
 -a 'complete' phobos reference w/ code snippets

 holy crap, i think D is awesome (thank you bright et al!!), but is this  
 asking
 for too much?? WTF?



I think language is not realy stable right now, so nobody take care of  
writing realy great docs of things that may change soon.



Just wanted to add that by "not realy stable", I think Dawid meant there are
still some changes being made to the language and libs., but those are primarily
additions. This is actually a good thing IMO - Walter has been continuously
implementing improvements along with the bug fix releases.

Both compilers and Phobos I think are reasonably stable (a lot of libraries and
some good size applications developed with them), and the last major change
where people had to do a wide-spread search-and-replace through their code was -
I think - a consolidation of some io modules, and that happened a few months ago
already, and only if they were using stream io.


D is awesome right now and will be awesone^2 when it'll reach it's next  
stage. And I bet it will have great docs even sooner. With help of this  
newsgroup, current docs and D sources you can get comfortable right now,  
but I know what you mean.

Just have to wait ... love don't come easy ... it's a game ... oh sorry  
... wrong place.
-- 
Dawid Ciężarkiewicz
Aug 16 2005
prev sibling next sibling parent reply "Charles" <noone nowhere.com> writes:
I agree , though I use PHP myself and love their documentation.


"prefetch" <prefetch_member pathlink.com> wrote in message
news:ddt4m3$h8q$1 digitaldaemon.com...

 hi all,

 i run a small engineering shop, and i've recently become very interested




 mainly because it is so much like C, killer performance, but without the




 all sorts of the nice properties that so many recent language have (like




 management, etc.)

 my background: software engineer, C/C++, some perl and python.

 anyway, about 72 hours ago i started on my quest: "let's explore D and see




 it's a good language to use for our next engineering project".

 so far, i'm still on the fence.

 my number one complaint is about the documentation.  it's HORRIBLE.  i




 this language is almost 5 years old, and the basic runtime library doesn't




 have a function index?  and it seems like i'm really lucky if i get a




 that includes expected return codes.

 if this language is ever going to make an impact, it needs some work on




 basic docs.  i think it's great that there are all these library projects




 on, but can someone who knows this language well PLEASE take a few days




 the docs usable??

 most of the last few days i've spent using the archaic search mechanism on




 site to figure things out, but that's awful because the google search




 all the C++ docs/posts from digital mars - which is a mess to sort




 also, the web interface to this newsgroup has no search mechanism at all,




 that's no help.

 the most recent language i evaluated was python, and it's got fantastic
 documentation.  kudos to python!!  why can't D take a few days and bust




 *good* docs so people like me don't have to pound their heads against a




 try and figure out if i'm too dumb to understand the std.thread docs, or




 are just broken - or when i have to grep for 'sleep' in the phobos




 figure out if it's available since it isn't documented anywhere.  the list




 on.  i'm sure i'll figure all this our over the next 72-196 hours, but i




 most people will probably give up and say "D is cool, but it's not ready




 prime time yet" just because of the immaturity of the documentation.

 here are two simple suggestions that wouldn't take a couple of experienced




 developer too much time:

 -an index of all functions, with links to docs (or at least source)
 -a 'complete' phobos reference w/ code snippets

 holy crap, i think D is awesome (thank you bright et al!!), but is this




 for too much?? WTF?
Aug 16 2005
next sibling parent reply "Charles" <noone nowhere.com> writes:
Ugh , accidentaly hit send.

http://www.quit-clan.de/docwiki/view.php?pageid=1

There is a community based documentation site with a real nice layout.

Charlie


"Charles" <noone nowhere.com> wrote in message
news:ddta2m$o2j$1 digitaldaemon.com...

 I agree , though I use PHP myself and love their documentation.


 "prefetch" <prefetch_member pathlink.com> wrote in message
 news:ddt4m3$h8q$1 digitaldaemon.com...

 hi all,

 i run a small engineering shop, and i've recently become very interested




 mainly because it is so much like C, killer performance, but without the




 all sorts of the nice properties that so many recent language have (like




 management, etc.)

 my background: software engineer, C/C++, some perl and python.

 anyway, about 72 hours ago i started on my quest: "let's explore D and







 if

 it's a good language to use for our next engineering project".

 so far, i'm still on the fence.

 my number one complaint is about the documentation.  it's HORRIBLE.  i




 this language is almost 5 years old, and the basic runtime library







 even

 have a function index?  and it seems like i'm really lucky if i get a




 that includes expected return codes.

 if this language is ever going to make an impact, it needs some work on




 basic docs.  i think it's great that there are all these library







 going

 on, but can someone who knows this language well PLEASE take a few days




 the docs usable??

 most of the last few days i've spent using the archaic search mechanism







 the d

 site to figure things out, but that's awful because the google search




 all the C++ docs/posts from digital mars - which is a mess to sort




 also, the web interface to this newsgroup has no search mechanism at







 so

 that's no help.

 the most recent language i evaluated was python, and it's got fantastic
 documentation.  kudos to python!!  why can't D take a few days and bust




 *good* docs so people like me don't have to pound their heads against a




 try and figure out if i'm too dumb to understand the std.thread docs, or




 are just broken - or when i have to grep for 'sleep' in the phobos




 figure out if it's available since it isn't documented anywhere.  the







 goes

 on.  i'm sure i'll figure all this our over the next 72-196 hours, but i




 most people will probably give up and say "D is cool, but it's not ready




 prime time yet" just because of the immaturity of the documentation.

 here are two simple suggestions that wouldn't take a couple of







 D

 developer too much time:

 -an index of all functions, with links to docs (or at least source)
 -a 'complete' phobos reference w/ code snippets

 holy crap, i think D is awesome (thank you bright et al!!), but is this




 for too much?? WTF?
Aug 16 2005
next sibling parent AJG <AJG_member pathlink.com> writes:
http://www.quit-clan.de/docwiki/view.php?pageid=1
There is a community based documentation site with a real nice layout.



Oh, wow. That is _nice_. Good find, man!
--AJG.
Aug 16 2005
prev sibling parent reply prefetch <prefetch_member pathlink.com> writes:
thanks charles, but there is simply no content there yet.

i think it's the responsibility of digital mars to at least make their bare
bones documentation (phobos) complete and accurate.

hey, but i'm new here - maybe i'm out of line.  it just seems to me that if this
sort of basic documentation is missing then the adoption for production use will
be stunted.  then again, maybe D is on a 10 year plan and we're only half way
there.

In article <ddta42$o54$1 digitaldaemon.com>, Charles says...

Ugh , accidentaly hit send.

http://www.quit-clan.de/docwiki/view.php?pageid=1

There is a community based documentation site with a real nice layout.

Charlie
Aug 16 2005
parent reply Lars Ivar Igesund <larsivar igesund.net> writes:
prefetch wrote:


 
 thanks charles, but there is simply no content there yet.
 
 i think it's the responsibility of digital mars to at least make their
 bare bones documentation (phobos) complete and accurate.
 
 hey, but i'm new here - maybe i'm out of line.  it just seems to me that
 if this sort of basic documentation is missing then the adoption for
 production use will
 be stunted.  then again, maybe D is on a 10 year plan and we're only half
 way there.



You're not really out-of-line, but Digital Mars is a one man show,
implementing both a C++, D and ECMA-interpreter, among other things. Thus
thourough documentation of an unstable API seems rather minor priority for
the main man. Note that there are possible, communitydriven, replacements
underway (www.dsource.org/projects/ares) that might be better documented if
the community wants it.

Lars Ivar Igesund
Aug 16 2005
parent reply prefetch <prefetch_member pathlink.com> writes:
You're not really out-of-line, but Digital Mars is a one man show,
implementing both a C++, D and ECMA-interpreter, among other things. Thus
thourough documentation of an unstable API seems rather minor priority for
the main man.



hm.  sounds like an alligator/swamp problem.  we can't drain the swamp because
we're busy fighting off aligators, and there are too many aligators because we
can't drain the swamp.

or maybe the leaky bucket metaphor works better here?

until you stop and properly document a basic runtime library, the support
required to grow a strong stable language won't come.

again, this is just from an engineering management position - if the one-man
show is too busy to make basic, accurate documentation, and the veterans in the
community are unable to help, then i don't think this language will go
mainstream.  just my $.02

at this point, i've started just reading the source instead of looking at the
docs, which is a shame.  it takes away from some of the "D is written to be
fast" because as we all know, execution time is only 1/2 of speed - the other is
development time. :-/
Aug 16 2005
parent "Charles" <noone nowhere.com> writes:
 at this point, i've started just reading the source instead of looking at




 docs



You might try Elephant www.thecodebase.com .  If you create a phobos
'project' , there is a class browser that will show all modules / classes /
functions etc.  Granted its a pain to add all those files by hand , the next
version will have a 'Add Dir' option that will recreate the filesystem
structure and add all the files to the project.

Charlie


"prefetch" <prefetch_member pathlink.com> wrote in message
news:ddtgdi$u6k$1 digitaldaemon.com...

You're not really out-of-line, but Digital Mars is a one man show,
implementing both a C++, D and ECMA-interpreter, among other things. Thus
thourough documentation of an unstable API seems rather minor priority







the main man.



 hm.  sounds like an alligator/swamp problem.  we can't drain the swamp




 we're busy fighting off aligators, and there are too many aligators




 can't drain the swamp.

 or maybe the leaky bucket metaphor works better here?

 until you stop and properly document a basic runtime library, the support
 required to grow a strong stable language won't come.

 again, this is just from an engineering management position - if the




 show is too busy to make basic, accurate documentation, and the veterans




 community are unable to help, then i don't think this language will go
 mainstream.  just my $.02

 at this point, i've started just reading the source instead of looking at




 docs, which is a shame.  it takes away from some of the "D is written to




 fast" because as we all know, execution time is only 1/2 of speed - the




 development time. :-/
Aug 16 2005
prev sibling parent AJG <AJG_member pathlink.com> writes:
Hi,


I agree , though I use PHP myself and love their documentation.



Indeed. The PHP docs single-handedly turn the PHP language from:

Highly inconsistent use of functions, variables, parameters and naming in
general, in addition to lots of irregularities between versions.

To:

Incredibly useful in spite of it. 

IMHO if it weren't for the PHP docs, and their impressive mirroring and
localization capabilities, PHP wouldn't have been nearly as succesful.

I particularly like the live commenting, because as we know, docs can be
confusing, weird, or just plain wrong at times.

This is better than a full-blown wiki because it's a better balance of
authoritative ("official") information with responsive feedback.


 holy crap, i think D is awesome (thank you bright et al!!), 
 but is this asking for too much?? WTF?






Nope, I don't think you are asking for too much.

D docs, get your act together.
--AJG.
Aug 16 2005
prev sibling next sibling parent "Ben Hinkle" <bhinkle mathworks.com> writes:
 my number one complaint is about the documentation.  it's HORRIBLE.  i 
 mean,
 this language is almost 5 years old, and the basic runtime library doesn't 
 even
 have a function index?  and it seems like i'm really lucky if i get a 
 definition
 that includes expected return codes.



I agree the phobos doc need work. There are whole modules that are 
undocumented from what I can tell (eg std.math2, std.loader). Even the doc 
for Object isn't accurate (it's missing opEquals) Also the phobos modules 
themselves need work. The topic flares up every now and then but I guess 
with the summer vacations people haven't been posting alot about it. 
Personally I'm still not sure what the scope is for changing phobos or 
unifying it more. Right now files have lots of different copyright and/or 
licenses and coding styles and it's not easy figuring out how the thing fits 
together. A fairly old post about process
http://www.digitalmars.com/d/archives/digitalmars/D/20303.html
seems to indicate posting changes to send to Walter and then just emailing 
him the changes would work. That would probably work fine for individual 
modules but structural or cross-module changes are an unknown. I don't know 
who should fix up the doc.
Aug 16 2005
prev sibling next sibling parent Mike Parker <aldacron71 yahoo.com> writes:
prefetch wrote:


 my number one complaint is about the documentation.  it's HORRIBLE.  i mean,
 this language is almost 5 years old, and the basic runtime library doesn't even
 have a function index?  and it seems like i'm really lucky if i get a
definition
 that includes expected return codes.



I agree that the docs are in bad shape, but I don't see that as an issue 
right now. They are enough to get started and point you in the right 
direction on most things. Obviously, the final release of the compiler 
and spec would be harmed if the docs are left in their current state, 
but I don't see that happening. I'm confident the docs will go through a 
complete overhaul before 1.0 is out the door. In the meantime, we work 
with what we have.


 the most recent language i evaluated was python, and it's got
 fantastic documentation.  kudos to python!!



I should hope so, considering it's been in a released state for several 
years! I don't think user documentation is ever a high priority on a 
project until the latter stages, and for a one man show like Digital 
Mars I wouldn't expect it to be. And considering how fluid the spec and 
features were for a while, I'm thankful to have any docs at all!
Aug 17 2005
prev sibling parent reply "Walter" <newshound digitalmars.com> writes:
You're right. I've reorganized the phobos doc a bit, at least it should be
easier to navigate now. Also, please use the [Comments] link whereever you
need it! -Walter

www.digitalmars.com/d/phobos.html
Aug 20 2005
parent AJG <AJG_member pathlink.com> writes:
In article <de8m9o$25pl$1 digitaldaemon.com>, Walter says...

You're right. I've reorganized the phobos doc a bit, at least it should be
easier to navigate now. Also, please use the [Comments] link whereever you
need it! -Walter



Wow, nice job! The frameless navigation is a _great_ improvement.

Hopefully the rest of the D spec will follow? ;)

Cheers,
--AJG.
Aug 20 2005