On Saturday, 4 June 2016 at 19:32:33 UTC, Andrei Alexandrescu wrote:
> On 6/4/16 2:33 PM, Vladimir Panteleev wrote:
>> [...]
>
> Sounds good to me, thanks. Delegation/lieutenantship/empowering for the win. I think we should also secure Martin's buy-in to make sure. -- Andrei

Nice idea! Maybe we can let step 2 follow quickly?

Reason: (from a recent discussion here [1])

> As someone who recently tried D and dropped it to learn Python [...] Two main issues I saw? Broken links and poor examples. Also occasionally I get pages that look like a different a style from google searches than the main documentation pages, which makes me feel one is outdated. I ended up actually just going to dlang.org itself to be sure...

[1] http://forum.dlang.org/post/ixpujamnyhguuqiflvom@forum.dlang.org

On Saturday, June 04, 2016 18:33:40 Vladimir Panteleev via Digitalmars-d wrote:
> On Saturday, 4 June 2016 at 16:10:14 UTC, Seb wrote:
> > Imho it's quite impressive that he still pushes the project and
> > as Adam
> > correctly said - we need to make a decision and have a clear
> > deadline like 2.072 will be the last documentation build with
> > ddoc, once it's released we will remove the ddoc Phobos build
> > and make ddox (/library) the standard (with redirect, of
> > course). This gives us also two to three months to test it
> > properly again (it has been tested now for 2.5 years!!) and
> > resolve issues if occurring.
>
> One wholesome switch is probably too harsh. We might discover new issues only after the switch. Instead it could be done gradually, in this order:
>
> 1. /library/ is promoted as the primary Phobos documentation in
> the site navigation.
> 2. /phobos/ is removed from search indexing.
> 3. /phobos/ is removed from site navigation.
> 4. /phobos/ is removed.
>
> We could start with step 1 upon 2.072's release.

I would point out that removing /phobos/ will break links elsewhere online. For instance, I know that I've linked to the documentation on numerous occasions in posts in the newsgroup and in answers on stackoverflow. All of those will break if /phobos/ is removed. If at all reasonably, possible, the old links should continue to work, even if they point to the new documentation.

- Jonathan M Davis

On Sunday, 5 June 2016 at 15:45:11 UTC, Jonathan M Davis wrote:
> I would point out that removing /phobos/ will break links elsewhere online. For instance, I know that I've linked to the documentation on numerous occasions in posts in the newsgroup and in answers on stackoverflow. All of those will break if /phobos/ is removed. If at all reasonably, possible, the old links should continue to work, even if they point to the new documentation.

Of course, by "removed" I mean "replaced with redirects".

On 06/05/2016 11:21 AM, Jacob Carlborg wrote:
> I found a minor issue recently. If there's more than one symbol in the same module with the same name but with different casing, all these symbols are shown on the same "single symbol page". Not sure if that's solvable due to some operating systems not using case sensitive file systems.

We specifically fix it that way.
[Issue 12526 – DDox possible issue with case sensitive file
names](https://issues.dlang.org/show_bug.cgi?id=12526)

If only the casing differs, the entities should always belong together.

-Martin

On 06/04/2016 09:32 PM, Andrei Alexandrescu wrote:
> Sounds good to me, thanks. Delegation/lieutenantship/empowering for the win. I think we should also secure Martin's buy-in to make sure. -- Andrei

I'm fine with switching to ddox, could have happened a while ago. Would be worth to switch for the auto-complete alone.

I'd want to disable or replace discourse before we make it our official documentation. We could easily self-host some commenting functionality if deemed necessary, but adding an unmaintained communication channel isn't the best idea IMO.

-Martin

On 06/04/2016 08:23 PM, Sönke Ludwig wrote:
> I think they have. Vladimir has reported a bunch of them over time and all of those have been fixed.

Found a new one ;).
[Issue 16152 – dpl-docs/ddox doesn't show documentation for eponymous
template member](https://issues.dlang.org/show_bug.cgi?id=16152)

On 6/10/16 3:17 PM, Martin Nowak wrote:
> On 06/04/2016 09:32 PM, Andrei Alexandrescu wrote:
>> Sounds good to me, thanks. Delegation/lieutenantship/empowering for the
>> win. I think we should also secure Martin's buy-in to make sure. -- Andrei
>
> I'm fine with switching to ddox, could have happened a while ago.
> Would be worth to switch for the auto-complete alone.

Awesome!

I should add that it would be valuable to keep the ddoc build as well. In my introductory material on D I discuss the basic elements of distribution: function, unittest, doc, deployment. It is compelling to mention that we build the stdlib documentation using the same means. An introduction to ddox at that point would be too much, and mentioning that "well ddoc isn't good enough for the official stdlib doc" does not sit well.

> I'd want to disable or replace discourse before we make it our official
> documentation. We could easily self-host some commenting functionality
> if deemed necessary, but adding an unmaintained communication channel
> isn't the best idea IMO.

I'm a bit bummed about that. I like it. Is my understanding incorrect that disqus is fairly established by now? I see it on a bunch of legit sites, and it seems to add value to those as it could add to ours.


Andrei

On 6/10/16 1:33 PM, Andrei Alexandrescu wrote:
> On 6/10/16 3:17 PM, Martin Nowak wrote:
>> I'd want to disable or replace discourse before we make it our official
>> documentation. We could easily self-host some commenting functionality
>> if deemed necessary, but adding an unmaintained communication channel
>> isn't the best idea IMO.
>
> I'm a bit bummed about that. I like it. Is my understanding incorrect
> that disqus is fairly established by now? I see it on a bunch of legit
> sites, and it seems to add value to those as it could add to ours.

I can see a good reason to have a disqus forum for each page, as I have found tremendous value from the php.net forums on each symbol (with common tricks to use with the given function).

But the problem is, people will ask questions on these forums, and likely will not get answers. I know I'm not going to peruse the docs looking for questions to answer. It's like adding 1000 black holes for newbies to get trapped in.

So what would be the use cases? If we have legitimate reasons to have it, that aren't better solved by routing back to the D forums, or back to github itself (e.g. if you have a trick to post, instead of using disqus, create a PR with the example!).

-Steve

On Friday, 10 June 2016 at 17:33:01 UTC, Andrei Alexandrescu wrote:
> I should add that it would be valuable to keep the ddoc build as well.

We need DDoc anyway for the website itself, as well as formats other than the website (e.g. CHM and HTML files distributed with the compiler), so it's not going away.

On 6/10/16 5:46 PM, Steven Schveighoffer wrote:
> On 6/10/16 1:33 PM, Andrei Alexandrescu wrote:
>> On 6/10/16 3:17 PM, Martin Nowak wrote:
>>> I'd want to disable or replace discourse before we make it our official
>>> documentation. We could easily self-host some commenting functionality
>>> if deemed necessary, but adding an unmaintained communication channel
>>> isn't the best idea IMO.
>>
>> I'm a bit bummed about that. I like it. Is my understanding incorrect
>> that disqus is fairly established by now? I see it on a bunch of legit
>> sites, and it seems to add value to those as it could add to ours.
>
> I can see a good reason to have a disqus forum for each page, as I have
> found tremendous value from the php.net forums on each symbol (with
> common tricks to use with the given function).
>
> But the problem is, people will ask questions on these forums, and
> likely will not get answers.

Why not? -- Andrei