On Sunday, 15 September 2013 at 19:29:56 UTC, Gary Willoughby wrote:
> Agreed. Sorry Andrei but this is not an improvement for usability. It disables being able to search the index via page search (Ctrl-F). Also i thought combobox navigation died out in the 90's!?

+1, combo boxes are terrible

Polishing ddox is much more promising approach.

On 2013-09-15 20:25, Vladimir Panteleev wrote:
> On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:
>> Vladimir, do you think you could easily implement such an incremental
>> search box (with autocompletion)?
>
> Sorry, that idea does not appeal to me either. Web browsers already have
> the function of searching within a page. An in-page search box is not a
> common UI element, users would need to learn to use it, and that's bad
> UX - we should stick to existing UI conventions to avoid forcing the
> users to think to get to their dox.

The Ruby documentation shows all core symbols (classes and methods) in one page with two filters. I like that. It's really useful when you know the name of the method/class you're looking for. It's also useful for guessing names. Like, is there a method called "sort". Then you find it you can figure out if it does what you think it will.

-- 
/Jacob Carlborg

On 2013-09-15 09:14, Andrei Alexandrescu wrote:
> I finally gathered strength to rebase
> https://github.com/D-Programming-Language/dlang.org/pull/271 manually,
> which was every bit as involved as I feared.
>
> I hope I didn't mess up anything, reviews appreciated.
>
> That diff includes a new page navigation scheme. (Wasn't the main
> purpose of the diff but found it a nice perk.) I see it as a
> transitional stage toward the larger transition to one-page-per-entity
> that Sönke has proposed.
>
> Check out the new navigation at
> http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list as
> the top gets replaced by a slick drop-down. Once you jump to a name, you
> can go back by pressing the up arrow on the right or simply go to top.

Can't we just use something like CandyDoc. This requires JavaScript but it actually improves the documentation. The version used by Tango looks like this:

http://dsource.org/projects/tango/docs/current/

It has a tree which list all packages and modules and a different tree which list the symbols in a module. It also has a filter for the tree. Simple and useable.

-- 
/Jacob Carlborg

Andrei Alexandrescu wrote:
> Of course better designs are welcome. One possibility is an incremental search box.

Best solution, IMO, would be using a categorized jump-list on the left that scrolls separately from the actual documentation (or each item could have it's own page). That way you get and "overview at a glance" of everything in the module, regardless of where you are. Similar to how MSDN works.

On 9/15/2013 11:38 AM, Sönke Ludwig wrote:
> Am 15.09.2013 19:20, schrieb Walter Bright:
>> On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:
>>> What happened with Ddox? This looks like an improvement in both
>>> function and
>>> aesthetics:
>>>
>>> http://vibed.org/temp/phobos/std/array.html
>>
>> It doesn't document the parameters, return type, and doesn't recognize
>> embedded hyperlinks.
>
> Just as a reminder, this is the current version:
> http://vibed.org/temp/d-programming-language.org/phobos/std/array.html

Much better!

On 9/15/13 11:25 AM, Vladimir Panteleev wrote:
> On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:
>> Vladimir, do you think you could easily implement such an incremental
>> search box (with autocompletion)?
>
> Sorry, that idea does not appeal to me either. Web browsers already have
> the function of searching within a page.

But search boxes with autocomplete are vastly better.

Andrei

On 9/15/13 11:43 AM, Jonathan M Davis wrote:
> On Sunday, September 15, 2013 10:47:06 Andrei Alexandrescu wrote:
>> On 9/15/13 12:53 AM, Vladimir Panteleev wrote:
>>> On Sunday, 15 September 2013 at 07:14:15 UTC, Andrei Alexandrescu wrote:
>>>> Check out the new navigation at
>>>> http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list as
>>>> the top gets replaced by a slick drop-down. Once you jump to a name,
>>>> you can go back by pressing the up arrow on the right or simply go to
>>>> top.
>>>
>>> I'm not sure this is an improvement, functionally. Finding the right
>>> item in much faster when you can see all items at once, and not lined up
>>> on only one direction.
>>
>> Not sure what that's based on, but at least for me that only works up to
>> a few words. For large modules that's hopeless. Just look at:
>>
>> http://dlang.org/phobos/std_datetime.html
>>
>> Can you really pick up the desired term? I think
>> http://erdani.com/d/phobos/std_datetime.html is a real improvement over
>> that (it also reduces the size of the list to the top-level ones, which
>> helps).
>
> It's an improvement because it shows the top-level symbols only rather than
> putting all of the symbols inside of the types at the top level like the
> current links do. The fact that it's a drop-down hurts rather than helps.
>
> - Jonathan  Davis

Probably I'll keep that in and drop the drop-down box.

Andrei

On 9/15/13 12:48 PM, Dicebot wrote:
> On Sunday, 15 September 2013 at 19:29:56 UTC, Gary Willoughby wrote:
>> Agreed. Sorry Andrei but this is not an improvement for usability. It
>> disables being able to search the index via page search (Ctrl-F). Also
>> i thought combobox navigation died out in the 90's!?
>
> +1, combo boxes are terrible

It's not a combo box.

Andrei

On 9/15/13 1:11 PM, Jacob Carlborg wrote:
> On 2013-09-15 20:25, Vladimir Panteleev wrote:
>> On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:
>>> Vladimir, do you think you could easily implement such an incremental
>>> search box (with autocompletion)?
>>
>> Sorry, that idea does not appeal to me either. Web browsers already have
>> the function of searching within a page. An in-page search box is not a
>> common UI element, users would need to learn to use it, and that's bad
>> UX - we should stick to existing UI conventions to avoid forcing the
>> users to think to get to their dox.
>
> The Ruby documentation shows all core symbols (classes and methods) in
> one page with two filters. I like that. It's really useful when you know
> the name of the method/class you're looking for. It's also useful for
> guessing names. Like, is there a method called "sort". Then you find it
> you can figure out if it does what you think it will.

Aha, I now remember - you mentioned this once, really like it.

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


Andrei

On Monday, 16 September 2013 at 01:52:38 UTC, Andrei Alexandrescu wrote:
> It's not a combo box.

http://msdn.microsoft.com/en-us/library/windows/desktop/bb775791%28v=vs.85%29.aspx

check out the CBS_DROPDOWNLIST style.

Or http://harmattan-dev.nokia.com/docs/library/html/qt4/qcombobox.html#details


BTW MSDN has something the D docs are really lacking: the conceptual overviews.

What are controls?
http://msdn.microsoft.com/en-us/library/windows/desktop/bb773173%28v=vs.85%29.aspx

What options are available?
http://msdn.microsoft.com/en-us/library/windows/desktop/bb773169%28v=vs.85%29.aspx

Big picture, what is a combo box?
http://msdn.microsoft.com/en-us/library/windows/desktop/bb775792%28v=vs.85%29.aspx

Can you tell me more?
http://msdn.microsoft.com/en-us/library/windows/desktop/bb775791%28v=vs.85%29.aspx

What about a complete example program?
http://msdn.microsoft.com/en-us/library/windows/desktop/hh298364%28v=vs.85%29.aspx

When I was new with Windows, half my programs were just bits of Microsoft examples (back then it was a .hlp file rather than a website though :) ) copy/pasted together. They're still useful today too.



Of course, D doesn't have the kind of resources Microsoft has, and those Windows documents were written over many years.

But we should start striving to at least offer:

1) conceptual overviews discussing the big idea and pointing to relevant modules. e.g. "Strings" or "Ranges". Put them right in the Phobos docs linked in all places like MSDN does with the "Related Topics" at the bottom of every page.

2) a big picture module overview on each and every one of them. Could just be a paragraph or two. Some already have this.

3) Collecting more full example programs. The samples directory in the dmd zip should be easily viewable online and open to more submissions. Is it on github?