January 07, 2015 Re: Ready to make page-per-item ddocs the default? | ||||
---|---|---|---|---|
| ||||
Posted in reply to Andrei Alexandrescu | On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote:
> Let's crowdsource the review. Please check the entries linked from here:
> http://dlang.org/library/index.html.
Looks nice! And will provide motivation to fix a lot of the under-documented functions.
|
January 07, 2015 Re: Ready to make page-per-item ddocs the default? | ||||
---|---|---|---|---|
| ||||
Posted in reply to Andrei Alexandrescu | On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote: > Let's crowdsource the review. Please check the entries linked from here: > http://dlang.org/library/index.html. In: http://dlang.org/library/std/algorithm/make_index.html if you click on the 'forward' link, it takes you to something quite unexpected. Looks like an issue with automatic cross referencing? |
January 07, 2015 Re: Ready to make page-per-item ddocs the default? | ||||
---|---|---|---|---|
| ||||
Posted in reply to Andrei Alexandrescu | On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote: > Let's crowdsource the review. Please check the entries linked from here: > http://dlang.org/library/index.html. The table: http://dlang.org/phobos/std_math.html#.cos got lost: http://dlang.org/library/std/math/cos.html Also, the 2$(SUP 64). got turned into 2,64. |
January 07, 2015 Re: Ready to make page-per-item ddocs the default? | ||||
---|---|---|---|---|
| ||||
Posted in reply to Andrei Alexandrescu | On 01/06/2015 05:43 PM, Andrei Alexandrescu wrote: > Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. > > Andrei On that page itself, the descriptions for at least std.regex and std.uni include the headers (e.g Intro, Overview) from those pages. -- Paul O'Neil Github / IRC: todayman |
January 07, 2015 Re: Ready to make page-per-item ddocs the default? | ||||
---|---|---|---|---|
| ||||
Posted in reply to Andrei Alexandrescu | On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com> wrote: > Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html. > > Andrei Very first function I looked at: http://dlang.org/library/std/string/format.html I find all the horizontal bar's throughout the docs quite noisy and tiring, and somewhat antiquated stylistically. I expected the parameters to jump out at me, but I didn't notice that that block surrounded by black lines and bold headings was actually the parameter list. I don't think I need headings to tell me which column is the name and which is the description. Ie, the parameters didn't jump out at me, the noise surrounding them did, and distracted me from the parameters themselves. There's obviously a bug here where the text is red too. My suggestions to make that page look more professional: * Prototype needs proper syntax highlighting, and elements (builtin types, types, template args, runtime args, and the function name itself) need to be styled distinctly (and tastefully). * The noise around the parameter listing can be removed completely. * The parameter name string in the parameter listing should match the styling of the prototype, so you can immediately recognise the thing in the prototype's description on the page. * The coloured box that houses the prototype is 6 times wider than it needs to be (on my monitor). I think it should be horizontally sized to fit the content. * Authors, license, and other uninteresting information should be spaced from the content (give an extra line-break or 2), and also the text should be significantly smaller. This is, literally, the fine-print. Comment box at the bottom is awesome! Taking another random sample: http://dlang.org/library/std/csv.html My previous criticisms stand equally. I feel like 'see also' should be the last thing before the 'fine print', not the first thing. Clicking through to see a class: http://dlang.org/library/std/csv/csv_exception.html Prior criticisms apply, but looks okay otherwise. There is 'fields' and 'methods', but they look the same. This is unexpected, since methods are functions, with return types, and arguments... why can't I see those? I'll leave it there for a moment. How do we style this stuff? Is there some way that we can experiment with styling ourselves? |
January 07, 2015 Re: Ready to make page-per-item ddocs the default? | ||||
---|---|---|---|---|
| ||||
Posted in reply to Andrei Alexandrescu Attachments: | On Tue, 06 Jan 2015 14:43:45 -0800
Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com>
wrote:
> Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html.
so looking at the function documentation i lost that nice indexes. if i got to the function directly (which will be very likely with googling), now i have to either drop keyboard and use mouse to click on module name (which is not immideately pops like a link, btw), possibly scrolling the page to top, or try to use keyboard navigation, which has only one thing in common for various browsers: it's awful. on the previous version it was not only enough to press "home" and see that, i was able to start quicksearching for other functions and read all the documentation without reloading the page (now two pages, actually).
i don't know about others, but for me new version is like a modern smartphone: shiny, cool, looking pretty and making phone talks worser.
|
January 07, 2015 Re: Ready to make page-per-item ddocs the default? | ||||
---|---|---|---|---|
| ||||
Posted in reply to Steven Schveighoffer | On 1/6/15 6:17 PM, Steven Schveighoffer wrote: > On 1/6/15 5:43 PM, Andrei Alexandrescu wrote: >> Let's crowdsource the review. Please check the entries linked from here: >> http://dlang.org/library/index.html. > > std.algorithm has many of the "descriptions" showing samples. Also, I > know the table at the top is to make things easier for standard ddoc, > should that be removed? But I like it. > BTW, I'm all for the docs to be switched. Just the cross-referencing > alone is worth it. One thing we need to do is offer for each module "view as one page" so people still have that option. Andrei |
January 07, 2015 Re: Ready to make page-per-item ddocs the default? | ||||
---|---|---|---|---|
| ||||
Posted in reply to Walter Bright | On 1/6/15 7:20 PM, Walter Bright wrote: > On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote: >> Let's crowdsource the review. Please check the entries linked from here: >> http://dlang.org/library/index.html. > > The table: > > http://dlang.org/phobos/std_math.html#.cos > > got lost: > > http://dlang.org/library/std/math/cos.html > > Also, the 2$(SUP 64). got turned into 2,64. https://github.com/D-Programming-Language/phobos/commit/7e766e6796a494de5a55c11d106889b47c303eff Andrei |
January 07, 2015 Re: Ready to make page-per-item ddocs the default? | ||||
---|---|---|---|---|
| ||||
Posted in reply to Andrei Alexandrescu | On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html.
>
> Andrei
Another one; I tried to use the search box on the top right corner...
it just resulted in a google search.
Can we do better than that? When people go to the documentation page,
they want to search the docs, not get a standard google results page.
|
January 07, 2015 Re: Ready to make page-per-item ddocs the default? | ||||
---|---|---|---|---|
| ||||
Posted in reply to Paul O'Neil | On 1/6/15 7:27 PM, Paul O'Neil wrote:
> On 01/06/2015 05:43 PM, Andrei Alexandrescu wrote:
>> Let's crowdsource the review. Please check the entries linked from here:
>> http://dlang.org/library/index.html.
>>
>> Andrei
>
> On that page itself, the descriptions for at least std.regex and std.uni
> include the headers (e.g Intro, Overview) from those pages.
>
Thanks! -- Andrei
|
Copyright © 1999-2021 by the D Language Foundation