Is enum static?

[H. S. Teoh]

On Thu, Aug 08, 2013 at 10:00:08PM -0400, Jonathan M Davis wrote:
> On Thursday, August 08, 2013 16:05:24 H. S. Teoh wrote:
[...]
> > But honestly, I can totally understand why many people find D docs
> > very frustrating. In fact, I found the online docs so unhelpful when
> > I first found D, that it delayed my adopting D for at least half a
> > year until one day I saw TDPL in a local bookstore and decided to
> > buy it. A friend of mine has told me, in private, that after trying
> > out D he liked the language, but one of the things he decidedly did
> > NOT like was the docs.  I think the only real solution to this is to
> > hire a full-time tech writer to do the documentation, and do it
> > *properly*. We're doing a great language a great disservice by
> > documenting it so poorly.
> 
> A lot of the problem stems from the fact that most of the devs don't
> do anything with the documenation. We tend to focus on the code and
> forget about the documentation. Maybe we need someone to champion the
> documentation and at least organize what needs to be done with it if
> not take the time themselves to fix it.

Yeah, that's why I said we should hire a full-time tech writer. We
coders are notoriously bad at writing docs. We're too familiar with the
code, and unconsciously make unstated assumptions that others don't know
about, so the little docs that we *do* write tend to be hard for newbies
to understand. I don't see any other way to solve this problem... it's a
common malady among opensource projects.


> The other big issue would probably be the fact that it's also treated
> as the spec for the language, and you don't write the same kind of
> documentation when you're writing a spec as when you're writing
> something to teach people (not that D's docs are quite what a spec
> requires either, as they don't tend to be precise enough, but they
> tend to lean heavily in that direction and aren't even vaguely meant
> as tutorials).
[...]

When is the Akeron project coming to fruition? ;-)

One of these days, we need to go back through the D-learn archives and
collect frequently-encountered problems by newbies, and write suitable
tutorials for them (say on the wiki or something).


T

-- 
Having a smoking section in a restaurant is like having a peeing section
in a swimming pool. -- Edward Burr