On 12/21/12 7:52 PM, Rob T wrote:
> On Saturday, 22 December 2012 at 00:00:43 UTC, Brad Roberts wrote:
>> The current separate wiki pages that mirror the dlang site are the worse
>> of both worlds in that the content exists, is hardly ever folded in, and
>> isn't even visible along side the page but hidden off behind a link
>> that I
>> bet most people never even see.
>>
>> Thoughts?
>>
>> Later,
>> Brad
>
> I think the reason for the disconnection is due to the docs not being
> stored with the wiki and I don't see what can be done to merge the two
> since they are two completely separate and different sources of
> documentation.

Behold: http://us3.php.net/manual/en/function.exp.php

> BTW, it turns out I didn't notice the wiki link until after reading your
> post! The link should be a button or something else that's much more
> noticeable and friendly for users to explore.

Even better, I think the content should be inlined!!!

> One grip do I have is that the "improve this page" system is rather
> unfriendly, and because of this I've not yet taken the time to research
> what I have to do to get to the point where I can contribute
> improvements. I suspect it turns away most people who otherwise would
> try and contribute.

Making it too easy may escalate moderation needs.

> In any event, what I see with the new document format is a very very
> large improvement and the sooner it is implemented (even with some of
> the minor flaws not yet fixed) the better.

Agreed.


Andrei

On 12/10/2012 2:31 PM, 1100110 wrote:
> I've had dail-up, I've had satelite internet.
> "Only" is indeed the appropriate word to use.

I've had floppy disks :-)

It's still hard to get used to the superfast disks we have these days.

On Saturday, 22 December 2012 at 02:36:44 UTC, Andrei Alexandrescu wrote:

> I was referring only to the actual word.

Ah I see, but it's still debatable to remove, although not a big deal either way.

> Behold: http://us3.php.net/manual/en/function.exp.php

I understand what you mean now, just didn't at first. What I see looks very good in the php page.

> Even better, I think the content should be inlined!!!

Yes, that would be much better.

> Making it too easy may escalate moderation needs.

I see the point there. Improved wiki integration as suggested should be a good compromise.

--rt

On 12/21/12 10:27 PM, Rob T wrote:
>> Behold: http://us3.php.net/manual/en/function.exp.php
>
> I understand what you mean now, just didn't at first. What I see looks
> very good in the php page.

I think there's a lot to be said about the contribution of PHP's excellent documentation to the success of an otherwise unremarkable language.

Andrei

On Saturday, 22 December 2012 at 03:34:55 UTC, Andrei Alexandrescu wrote:
> On 12/21/12 10:27 PM, Rob T wrote:
>>> Behold: http://us3.php.net/manual/en/function.exp.php
>>
>> I understand what you mean now, just didn't at first. What I see looks
>> very good in the php page.
>
> I think there's a lot to be said about the contribution of PHP's excellent documentation to the success of an otherwise unremarkable language.
>
> Andrei

Ease of adoption is very important, and good documentation is certainly a big part of that. Another thing that helps is having a very good tool set for the programmers to use.

--rt

Am 22.12.2012 00:46, schrieb Andrei Alexandrescu:
> On 12/21/12 7:24 AM, Sönke Ludwig wrote:
>> Example generated site is here:
>>
>> http://vibed.org/temp/d-programming-language.org/phobos/index.html
>>
>>
>> Is any further work on this desired?
> 
> Thanks for this work! Let me provide a little feedback. I'm looking mainly at std.array and std.algorithm.

Thanks for the feedback. I'll continue to improve things along the way.

> 
> * There's lots of wasted real estate at the top of the page: the source, license, and authors sections are way spaced. They should compactly fill the top of the page.

I'll try to get closer to the original there. There are some differences because the current pages use a lot of non-semantic formatting (<b>, <br> etc) and the result of this needs to be simulated using CSS now.

> 
> * Differentiating "Functions" and "Templates" is unnecessary and tenuous. Generic functions are functions. Everything should go in one place.

This is actually a bug of the JSON output. Sometimes it will just output a simple "template" node instead of "function" nested in a "template". In that case there is not much I can do, unfortunately. But I hope that this will be addressed by the big DDOC pull request.

> 
> * The paragraph heading "Functions:" followed immediately by "Function name" is redundant.

Right. Any preference? I would go for header + only "Name" in the table to keep it visually structured (I actually could have sworn I already did that some time ago, but the commit is probably lying locally on another machine).

> 
> * The individual pages repeat the text on the page. We should have a way to differentiate the blurb from the full description. For example:
> 
> // inside array.d
> /**
> $(BLURB Replace occurrences of from with to in subject.) Returns a new array without changing the
> contents of subject, or the original array if no match is found.
> */
> E[] replace((E,R1,R2) if (isDynamicArray!(E[]) && isForwardRange!(R1) && isForwardRange!(R2) &&
> (hasLength!(R2) || isSomeString!(R2))))(   E[] subject,   R1 from,   R2 to ) { ... }
> 
> The blurb would be present in the short doc, and the blurb followed by the rest of the text and the signature would appear in the full page.

The DDOC spec says that the first paragraph is the short summary (BLURB), followed by the long summary, which goes until the first section header. Some modules are not using this correctly and have a very long paragraph at the beginning.

(See http://dlang.org/ddoc.html under "Sections")

So currently the short description is repeated on the individual page, because there often is distinct content in it. That would also be an interesting documentation style decision, if the long summary must be able to stand alone (which would probably be nicer).

> 
> * "Module" in the title is redundant I guess.

Due to the naming convention (module/package names lowercase) it somehow is. But for the individual pages, the distinction of class, struct, enum, function etc. is important. Putting "Module" in front of the module name is consistent with the other pages in this regard. But I have no strong feeling about this either.

> 
> * The styling on the "+" signs in the left column should be different when the tree branch is open or closed.

Agreed. The current icon is just a place holder. Any style precedence or preference? (e.g. old windows style with +/- or the new triangle thing)

> 
> * I yearned for a long time for a per-symbol page, and I'd be really happy to migrate toward that. One important consequence here is that we can improve each function's (struct's, class' etc) documentation without bloating the general documentation, which remains terse. In that vein, I'm looking at the PHP docs (which have opted for a similar structure) and that are of excellent quality. See e.g. http://us1.php.net/manual/en/function.fopen.php that inspires a few bullets below.

Yeah, that's the really nice aspect of it. You can actually feel the urge to write more detailed
documentation because of this (at least I can ;) ).

> 
> * There's a "Changelog" section which we can add to help with any backward compatibility issue.
> 
> * "See also" is awesome.
> 
> * But by very, very far the community-contributed stuff is just perfect. I really really really hope we can get something like that integrated. There are many ways to approach this:
> 
> - By integrating a wiki page via e.g. an IFRAME.
> - By integrating with github
> - Through a separate custom layer (a la forum.dlang.org)
> - Whatever it is, we'd need some crowdsourcing (voting system etc) such that good community notes go
> up and bad notes go down or get ultimately deleted.

An easy option would be http://disqus.com/ - I've seen this used quite often recently.

Btw., regarding sections, if, at some point, we want to visually separate individual sections (or make them collapsible), a careful pass through Phobos will be necessary, because sections are often introduced accidentally (e.g. a line "Example:" before a code block or "Copyright: ... on a single line), resulting in an illogical structure.

> 
> * Would be awesome to have the implementation at entity level in an expandable IFRAME instead of linking to the entire github implementation of the file.
> 

A simple improvement would be to at least use a line anchor and automatically scroll to the right line. Displaying only the entity would require a new JSON field for the ending line of an entity (and some more work, of course).

On 2012-12-21 13:24, Sönke Ludwig wrote:

> Is any further work on this desired? If so, what would be the next steps to integrate it into the
> general dlang.org workflow? (or rather, how is that workflow in terms of folder structure, build
> scripts etc.?)
>
> It would also need a phase of bug fixing regarding some macros used in the Phobos ddoc comments.

I think it would be really nice to have a list of all symbols with a filter, just like the Ruby docs have:

http://www.ruby-doc.org/core-1.9.3/

-- 
/Jacob Carlborg

On 12/22/12 10:16 AM, Jacob Carlborg wrote:
> On 2012-12-21 13:24, Sönke Ludwig wrote:
>
>> Is any further work on this desired? If so, what would be the next
>> steps to integrate it into the
>> general dlang.org workflow? (or rather, how is that workflow in terms
>> of folder structure, build
>> scripts etc.?)
>>
>> It would also need a phase of bug fixing regarding some macros used in
>> the Phobos ddoc comments.
>
> I think it would be really nice to have a list of all symbols with a
> filter, just like the Ruby docs have:
>
> http://www.ruby-doc.org/core-1.9.3/

Looks great! I think that belongs in an index page (which doesn't exist yet, though we do define a sitemap http://dlang.org/sitemap.html).

Andrei

>> * There's lots of wasted real estate at the top of the page: the source, license, and authors sections are way spaced. They should compactly fill the top of the page.
> 
> I'll try to get closer to the original there. There are some differences because the current pages use a lot of non-semantic formatting (<b>, <br> etc) and the result of this needs to be simulated using CSS now.
> 

Continuing the thought of screen real estate - shouldn't these sections better be at the _bottom_ of the page? After all they are just noise for the typical reader and since the pages are not as long anymore, they still won't get drowned by the rest of the page.

On 12/22/12 11:49 AM, Sönke Ludwig wrote:
>>> * There's lots of wasted real estate at the top of the page: the source, license, and authors
>>> sections are way spaced. They should compactly fill the top of the page.
>>
>> I'll try to get closer to the original there. There are some differences because the current pages
>> use a lot of non-semantic formatting (<b>,<br>  etc) and the result of this needs to be simulated
>> using CSS now.
>>
>
> Continuing the thought of screen real estate - shouldn't these sections better be at the _bottom_ of
> the page? After all they are just noise for the typical reader and since the pages are not as long
> anymore, they still won't get drowned by the rest of the page.

Good idea. I'm a big fan of moving uninteresting stuff off the top of a page. Maybe the source does carry some interest though.

More creative ideas is to represent all that information not in normal paragraph style, but as small print in a band (horizontal or even vertical) etc.

Andrei