Better docs for D (WIP)

[Rory McGuire via Digitalmars-d-announce]

On Wed, Jan 6, 2016 at 10:01 PM, Martin Nowak via Digitalmars-d-announce <
digitalmars-d-announce at puremagic.com> wrote:

> On Wednesday, 6 January 2016 at 15:41:29 UTC, Adam D. Ruppe wrote:
>
>> I know projects get bugs open when they are used, but ddox is a
>> one-person project and that one person doesn't seem terribly active in it.
>>
>
> I'm another user of ddox and fix things when they annoy me.
> I don't have many problems with it though.
> It you'd joined we'd already be 3.
>
> https://github.com/rejectedsoftware/ddox/graphs/contributors
>>
>
> The main reasons why work has stalled is that the future of dpl-docs is
> unclear. Instead of fixing the remaining issues w/ ddox people have spend a
> huge amount of time to improve ddoc output, so b/c of this weird course
> Söhnke stopped working on dpl-docs for now.
> The other reason is that the existing tool already does most things you
> want from a documentation system. The styling sucked so I wrote scod, but
> most of the remaining issues are minor problems that will eventually be
> addressed. And even if you don't agree w/ some aspect of it, working on a
> common documentation engine/library makes more sense than having everyone
> write it's own, in particular if you're arguing about limited time.
>

I like our current documentation. The only real barrier to entry for non D
devs is the weird symbols names we've used for the standard library. They
are good names, but they are "sciency". It would be great if people could
"tag" symbols in the current documentation website. That way anyone could
put things like "go:Dial" in the tags for Socket's "@safe this(Address
connectTo);" and "js:contains" in the tags for canFind(). All the symbols
in std.algorithm.setops could use some less "sciency" tags.

If not a tagging system then at least adding synonyms would be great.

The documentation on Google Developers is excellent for api discovery, our
docs are quite similar I think. (In our company even sales and lead gen use
the Google Developers docs to check if something is possible.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d-announce/attachments/20160107/23df4134/attachment.html>