d-programming-language.com

[Manu]

On 11 December 2011 02:00, Walter Bright <newshound2 at digitalmars.com> wrote:

> On 12/10/2011 3:45 PM, Manu wrote:
>
>> Cool cheers, noted, although to be completely honest, I'm a windows user,
>> and I
>> will never type this. There should be a .chm in the distribution, which
>> is the
>> standard expected by any windows developer from any sdk they intend to
>> take
>> seriously. This is very easy to produce from the existing webpage,
>> although
>> indexing it might take some investment.
>>
>
> I didn't think anyone preferred chm over web pages anymore!
>

Definitely the standard where I'm from (10 years in the video games
universe, almost exclusively windows based sdk's). The expected
functionality is to have the chm open sitting there while you work, type
the first 2-3 letters of the keyword, function name, etc into the 'index'
list, the topic appears and you immediately have your answer. There is also
a lightning fast 'search' there for more abstract topics.
The DirectX documentation is usually held in the highest regard by most
people I've worked with, it's among the best examples of 'perfect'
documentation as considered by any windows based developer. Most console
vendors provide a similarly high quality and formatted set of reference
material.

That would be ideal, but that said, I'd be happy with the website if it
were complete, and I didn't have to start digging every time I look
something up. And even then, the descriptions are often vague, and I find
myself chasing examples before I can even understand the documentation (see
std.concurrency) ;) ... (note: I'm still failing to solve my problems, all
with sharing and access rights to local variables passed between threads)

In abstract, for me, as an end user of the language/libraries, my
experience/expectations with most SDK's is that if it takes me longer than
10-20 seconds or so to get the answer to a trivial question, short, concise
and articulate, I start to feel frustrated and like I'm wasting time.
I think it leaves a really good impression with new comers to the language
if they can just get into it and feel immediately productive. After all, I
think for a lot of people (including myself), the promise of D is that of
"C++ done right". If I can't just start coding and feel generally
productive (sure, some language differences will take some time to adapt
to), then it really dilutes that dream very quickly, which is what, I
think, will attract most new comers to the language. So it's imperative to
get that part just right, and that's all about the docs and presentation
for me.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20111211/990ccf9f/attachment-0001.html>