On Friday, 16 August 2013 at 20:42:28 UTC, H. S. Teoh wrote:
> On Fri, Aug 16, 2013 at 10:24:55PM +0200, Andre Artus wrote:
>> On Friday, 16 August 2013 at 17:45:35 UTC, Suliman wrote:
>> >On Friday, 16 August 2013 at 16:07:59 UTC, Andre Artus wrote:
>> >>I would like to contribute to the D ecosystem, but as I'm still
>> >>in the learning process I do not want to get my sticky fingers
>> >>all over someones nice clean code.
>> >>
>> >>I have poured over the documentation and see that there are a
>> >>few low-hanging fruit that I would like to pluck. So I have
>> >>decided to do so.
>> >>
>> >>I would like for there to be a section were people interested in
>> >>working on the docs can collaborate.
>> >
>> >It would be perfect to get D version of
>> >http://www.dotnetperls.com/
>> 
>> That's pretty cool. It would be good to have something like that for
>> D, or a "Ninety-Nine D Problems", or a Try-D, or an update to
>> http://en.wikibooks.org/wiki/D. I'm wiling to work towards those
>> goals. There are a number of good articles and other D materials
>> strewn around the web, perhaps we can find place to include or link
>> to them from dlang.org.
>
> I think wiki.dlang.org is a good place to put little gems like this. It
> allows easy community effort to edit, and serves as a central place for
> people to go when they want to find example D code for a particular
> task. Vladimir has been very kind to offer hosting for wiki.dlang.org,
> so let's make use of it.
>
>
> T

You have a good point, maybe we should consolidate the How-to's and the Articles on one or the other site and provide links to it from the other site.

For the time being I think getting the Library and Language references cleaned up could probably be of greatest value.

On Friday, 16 August 2013 at 20:03:10 UTC, H. S. Teoh wrote:
> On Fri, Aug 16, 2013 at 08:25:00PM +0200, Andre Artus wrote:
>> On Friday, 16 August 2013 at 18:09:04 UTC, Andrei Alexandrescu
>> wrote:
> [...]
>> >Things should happen organically, i.e. creating a specialized
>> >group should follow a need substantiated by increased volume of
>> >specialized discussion in the general group. At this point there
>> >is nothing in that vein.
> [...]
>> I understand were you are coming from. And, while I currently feel
>> that it's a bit of a catch-22 situation, I think it is worth at
>> least trying out your suggestion of marking document related threads
>> with "[dox]".
>
> Alright, I'll start.
>
> Here's a list of Phobos modules that need some documentation facelist.
> For fairness' sake, I gleaned these from:
>
> 	http://dlang.org/phobos-prerelease/index.html
> 	
> as opposed to the docs for the official release, so that they closer
> reflect what things will look like at the next D release.
>
> 1) The above page itself needs work. Right now it's just a very spotty
> incomplete list of seemingly-random pieces of Phobos. It looks like the
> relic from a bygone era before Phobos docs had a navbar on the left; so
> my first thought would be to kill off that incomplete module list (leave
> that to the navbar). My second thought would be to group the modules
> under more logical categories so that newbies would know which modules
> tend to be used together (e.g., std.algorithm and std.range tend to be
> used together a lot IME).
>
> 2) std.algorithm: the state of the current docs is not bad, but could
> use some improvement. The first paragraph could be expanded to explain
> what this module is all about. The part about string lambdas (2nd
> paragraph) may need to be tagged with a note about possible deprecation,
> judging from discussions in the other thread. If not, at the very least
> the code example should show how to use the new lambda syntax:
>
> 	sort!((a,b) => a < b)(...);
>
> I'm not sure what to make of the cheat sheet, as it seems to repeat most
> of the table of links at the top of the page. But maybe it's good for
> short code snippets to remind you how to use each function, so maybe it
> can be left alone for now.
>
> 3) std.array: desperately needs a more detailed explanation at the top
> to explain why this module is even needed (newbies would wonder: doesn't
> D have built-in arrays? Why do we need this module then?). Not enough
> code examples.
>
> 4) std.ascii: unhelpful description. Why do we even need this module
> when D uses UTF-8 by default? When should we use this module and when
> should we use std.uni? Also, needs an overview of what this module
> provides (string constants, character categorization, case conversions).
>
> 5) std.base64: unhelpful description. Doesn't explain what is base-64
> and why we should care. What are the applications of base-64 anyway?
> Who would want to use this stuff? Without more details, a newcomer
> wouldn't know.
>
> 6) std.bigint: badly needs more code examples, with explanations.
>
> 7) std.bitmanip: needs more explanation about what this module is, why
> we need it, etc.. Needs categorization of what is provided (bitfields,
> endianness-related functions, anything else).
>
> 8) std.compiler: need code examples of how to use the stuff here. Maybe
> using version blocks. Maybe sample music composed in D_major... oh wait.
> Wrong forum. :-P
>
> 9) std.complex: needs more code examples. Maybe a little more
> explanation about what's going on with "built-in types" and why those
> will be replaced.
>
> 10) std.concurrency: needs higher-level module description, like what's
> the use of low-level messaging systems. Need to provide adequate context
> for where/when this module should be used. Needs to link to other doc
> pages that discuss threads, processes, etc..
>
> 11) std.container: badly needs a better description. The table of
> operations with complexity guarantees needs a bit more explanation about
> what this all means. Maybe a link to somewhere (wikipedia perhaps) that
> explains the concept of complexity and why it matters. Also, need an
> overview of what containers are provided and example code on how to use
> them.
>
> 12) std.conv: the one-line description is cute, but inadequate. Need
> code examples on common usage. Need to explain in more detail how to
> make user-defined types usable with to!() (e.g., need to define opCast,
> ctor requirements, etc.). Need module overview about what's provided
> (to, octal, parse, emplace). Need code examples.
>
> 13) std.csv: Not bad, but could use an overview of module contents with
> links to each main function/struct (ala std.algorithm / std.range).
>
> 14) std.datetime: Not bad. It would be nice to add links to actual
> functions/types in the module overview.
>
> 15) std.encoding: needs more code examples. Overview of module contents.
>
> 16) std.exception: needs higher-level overview of what's in this module,
> with categorized functions/types.  Code examples for assertThrown & co.,
> as well as explanations of why we need them.
>
> 17) std.file: needs more code examples. Module contents overview.
>
> 18) std.format: there are a lot of good docs here, but buried in
> hard-to-find places. Needs module overview, with code examples. There
> also appear to be some DDOC typos here. Especially needed is: how to
> make your own user-defined types usable with std.format. What are the
> possible hooks, example code of how they are used, etc..
>
> 19) std.functional: need more explanation of what this module is all
> about. Motivation: why do we care about functions manipulating other
> functions? There are some code examples here but could use better
> motivated examples, like when/where such features would be useful. How
> this relates to functional programming, etc..
>
> 20) std.getopt: not bad. Maybe add some examples of an actual shell
> session and how getopt parses things. Explain what args[0] means (this
> is very non-obvious to people unfamiliar with command-line UIs!).
>
> 21) std.json: needs proper description and code examples.
>
> 22) std.math: needs categorized summary of module contents.
>
> 23) std.mathspecial: needs code examples. Explanation of why this isn't
> part of std.math.
>
> 24) std.mmfile: needs a LOT of explanation of what this is, and why it
> might be useful. Code examples.
>
> 25) std.numeric: needs adequate explanation of what this module does and
> why it's needed. Why isn't it part of std.math, what's the difference,
> etc.. Categorized summary of module contents.
>
> 26) std.outbuffer: needs explanation of what this module is. Code
> examples.
>
> 27) std.parallelism: not bad. A linked overview of module contents would
> be nice.
>
> 28) std.path: needs linked overview of module contents. Why this isn't
> part of std.file. In fact, the Phobos index page should group std.file,
> std.stdio, and std.path together, and explain what's the difference
> between them, and what each module covers in terms of file-related
> operations.
>
> 29) std.process: pretty good! Maybe explain how this relates to
> std.parallelism, std.concurrency, etc.. The difference may not be
> obvious to newcomers. Possibly put this explanation in the Phobos index
> page.
>
> 30) std.random: linked overview of module contents would be nice. More
> code examples. Maybe a brief discussion on various RNG issues, like
> measure of randomness, reproducible/non-reproducible sequences,
> cryptographic strength, etc..
>
> 31) std.range: not bad (if I say so myself ;-P). More code examples
> would be nice. As well as motivating examples of when you might want to
> use each range type.
>
> 32) std.regex: pretty good!
>
> 33) std.signals: ugly. The links to various forum discussion threads is
> a poor substitute for a well-written summary of the contents of said
> discussions. Needs more code examples and applications.
>
> 34) std.socket: needs a module description!! And many more code
> examples. And module contents overview.
>
> 35) std.socketstream: not sure if we want to spend more effort
> documenting this, since it's slated for replacement, but might not hurt
> in the short term to do so.
>
> 36) std.stdio: very unhelpful description. Should explain exactly what
> this module does for people who *don't* know C, what types / functions
> it exports, code examples of how to use them. E.g., how to open / close
> a file, how to read/write text data, how to read/write binary data.
> Explain range interface for files. Caveats on the transience of byLine.
>
> 37) std.cstream, std.stream: not sure how much to do for these, since
> they're slated for replacement.
>
> 38) std.string: need better description. Why this module exists (aren't
> strings built-in in D?), what it provides (linked overview of contents),
> more code examples.
>
> 39) std.system: explain what this module is, why we need it, when it
> should be used. Code examples (*motivating* code examples, not just
> random code snippets that happens to use the symbols exported here!).
> This should be grouped with std.compiler in the Phobos index page.
>
> 40) std.traits: need to elaborate on description. Brief discussion of
> metaprogramming maybe? With motivating code examples. Need linked
> overview of contents. There's a lot of stuff in here; grouping into
> logical categories should be more helpful.
>
> 41) std.typecons: need better description. Explain basic usage, what it
> means, etc.. The current code example is rather abstruse to a newcomer;
> needs more down-to-earth explanations of what exactly is going on in the
> code. Needs overview of contents. More code examples. Things like Flag
> should be highlighted so that newbies pick up on the concept and use
> Flag instead of bools everywhere.
>
> 42) std.typetuple: need proper explanation of the difference between
> TypeTuple, std.range.Tuple, and compile-time "tuples" (SymbolTuples, as
> Ali calls them). This is very confusing for newbies (and even for
> experienced D coders!). Overview of module contents.
>
> 43) std.uni: I think Dmitry's new std.uni hasn't been updated on
> dlang.org yet, so I'll refrain from commenting for now. From what I
> remember, the new docs (and code, of course!) are far better than the
> one you see on dlang.org, so probably we don't have to worry about it.
>
> 44) std.uri: the description could use some elaboration. And code
> examples.
>
> 45) std.utf: need to elaborate description. How this relates to std.uni.
> Example code. Issues to deal with when interfacing with C code
> (toUTF*z).
>
> 46) std.uuid: not bad!
>
> 47) std.variant: not bad. Could use more code examples in a few places.
> Maybe higher-level discussion of usage, motivation, potential issues,
> etc.. Overview of module contents.
>
> 48) std.xml: slated for replacement; so just let be for now?
>
> 49) std.zip: Need better module description, overview of contents. How
> this relates to std.zlib.
>
> 50) std.zlib: why this isn't part of std.zip. Code examples!!
>
> 51) std.net.curl: not bad.
>
> 52) std.net.isemail: need code examples!
>
> 53) std.digest.*: not bad! Phobos index page needs to group these
> together and explain how each piece relates to the others.
>
> 54) std.windows.charset: explain why this isn't part of std.encoding.
> Code examples. (Also, why is the CSS broken for this page on dlang.org?)
>
> Phew, I never realized Phobos was *this* big! This covers only std.*,
> but there's still etc.* and core.*. Lots of work ahead of us!
>
>
> T

This is great, I'm busy working on some parts of the Language docs so I have not read through your entire list, but I have a short example to core.time.

There is a script running on the page you linked to that is making my browser misbehave. It's probably not helped by the fact that I have a browser tab open for every page on the interwebs.

On Friday, August 16, 2013 14:04:48 H. S. Teoh wrote:
> Actually, there are several things going on here: the forums themselves are hosted on NNTP servers, but IIRC very few members actually use NNTP directly. Instead, some proportion use the SMTP mailing list gateway (which runs mailman, which has a long-unfixed issue which sometimes rewrites the wrong message IDs, causing threads to break), and others use the web interface on dlang.org.

I'm pretty sure that there are quite a few folks using NNTP still (e.g. IIRC, Walter uses Thunderbird as an NNTP client), but we'd have to do a poll to be sure. Certainly, a large portion of the posters who have been here for a while use either the mailing list or NNTP, since the current web interface is fairly new.

- Jonathan M Davis

On Friday, 16 August 2013 at 19:32:41 UTC, Mr. Anonymous wrote:
> On Friday, 16 August 2013 at 19:27:58 UTC, Andre Artus wrote:
>> On Friday, 16 August 2013 at 19:12:46 UTC, Mr. Anonymous wrote:
>>> On Friday, 16 August 2013 at 18:12:57 UTC, Andre Artus wrote:
>>>> Is there a way to break the pages into a more of a hierarchy, so that documentation for each module doesn't have to be on one page? Perhaps a DDOC Section could indicate the category?
>>>
>>> Are you familiar with DDOX?
>>> http://vibed.org/temp/d-programming-language.org/phobos/index.html
>>
>> I have not yet had the time to look into it, but I fear that it would be of little use if it's not the official way of doing docs. Although it may be the preferred option for private projects or projects not directly connected to the main D ecosystem. There is already quite a lot of fragmentation making it quite an effort to find out what the "one true path"[1] is.
>>
>>
>> 1. I realize that there isn't truly such a thing, but an opinionated starting point is of great help to noobs. The major feature to popularize Ruby on Rails when it first kicked off was, in my opinion, the "on rails" part. You had a very clear indication of where to start, and what the best/accepted/expected practices are. Once you have accustomed yourself to the language and framework you can find ways to go crashing through the bushes if you feel the need to do so.
>
> It's planned as the official way of doing docs.
> There are pull request for it, but it's going nowhere for the past several months.
> A related thread:
> http://forum.dlang.org/thread/dsnpggjmndaxiusfqhjk@forum.dlang.org

I have looked at it now, and it seems to me to be a great improvement but the content needs to be updated.

If this is going to be the new official way, and all that is needed is someone to start porting/updating the content then I'll sign up for that.

I think it wise to first get it up to date before doing major new additions. Who is working on this at the moment?