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