On 2012-12-21 18:05, Andrei Alexandrescu wrote:

> s/remove/integrate/
> s/ugly/awesome/

It's ugly that they are manually created. Over 300 lines of comments that the doc generator should be doing automatically. I would say that is far from awesome.

-- 
/Jacob Carlborg

On 2012-12-21 19:31, Sönke Ludwig wrote:

>>> What also would be nice is to have the methods inline, expandable.
>
> Would that mean the Classes/Structs/... tables as f.ex. in std.datetime?
> So there would be a small clickable thing and all members would fly out below it as direct links?
> and possibly with the short description?
> What about different kinds of members? Only methods, all grouped by type or all in one list?
>
> I'm just asking because I don't have any preferences for how such a thing should look like.

I was mostly thinking of the free functions. Instead of going to a new page when clicking on a function it would just expand the same content inline. For classes and structs we might want to keep the separate page since it will contain additional members. But I'm not sure.

-- 
/Jacob Carlborg

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.

* 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.

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

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

* 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.

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

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

* 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.

* 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.

* 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.


Thanks,

Andrei

On 12/21/12 6:46 PM, Andrei Alexandrescu wrote:
[snip]

Forgot to emphasize what I already mentioned: alphabetic order is okay, but I wonder how we can integrate that with grouping per functionality area (the way std.algorithm does).

Andrei

Andrei Alexandrescu:

> Thanks for this work! Let me provide a little feedback. I'm looking mainly at std.array and std.algorithm.

Compare a page like this:
http://dlang.org/phobos/std_array.html

With the docs of the Prelude module of Haskell:
http://www.haskell.org/ghc/docs/latest/html/libraries/base/Prelude.html

Similarly in the pages of D Phobos docs I'd like each function to have a link to its source, and not just have a single link to the whole module. This allows to find faster the source code of that function.

Bye,
bearophile

On Fri, 21 Dec 2012, Andrei Alexandrescu wrote:

> * 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.
> 
> * 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.

I love community / croudsourcing.  But where it falls down in most of the examples I've seen is that the majority of the feedback / comments really belong as edits to the actual content, not additional notes.  We need to aim for making both happen, imho.  Allow ad-hoc extra feedback, but also get it cycled into the core page contents.

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

On Friday, 21 December 2012 at 23:46:05 UTC, Andrei Alexandrescu wrote:
>
> * "Module" in the title is redundant I guess.
>

I don't think it is redundant because when you are looking at a page, the module as the title instantly tells you (or reminds you) what module you are looking at, otherwise you'll have to do a little bit more digging than should be necessary.

--rt

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.

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.

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.

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.

--rt

On 12/21/12 7:16 PM, Brad Roberts wrote:
> I love community / croudsourcing.  But where it falls down in most of the
> examples I've seen is that the majority of the feedback / comments really
> belong as edits to the actual content, not additional notes.  We need to
> aim for making both happen, imho.  Allow ad-hoc extra feedback, but also
> get it cycled into the core page contents.

The way I see it, changes to the core page contents go via github. The community-provided notes are crowdsourced and occasionally moderated.

> 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?

That's why I'm saying the wiki pages should be accessible immediately alongside the abstractions they document.


Andrei

On 12/21/12 7:29 PM, Rob T wrote:
> On Friday, 21 December 2012 at 23:46:05 UTC, Andrei Alexandrescu wrote:
>>
>> * "Module" in the title is redundant I guess.
>>
>
> I don't think it is redundant because when you are looking at a page,
> the module as the title instantly tells you (or reminds you) what module
> you are looking at, otherwise you'll have to do a little bit more
> digging than should be necessary.
>
> --rt

I was referring only to the actual word.

Andrei