www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Fixed date to move to ddox for Phobos documentation

reply Seb <seb wilzba.ch> writes:
More than two and half years ago, Sönke added ddox builds for the 
Phobos documentation. We all know that there are many reasons for 
ddox - being able to generate single pages for methods is just 
one, it also eliminates all the JavaScript hacks (e.g. the 
quickindex menu, anchors, ...) that we have added over time to 
deal with the shortcomings of ddoc.

This post originates from a recent discussion [2] that showed the 
higher ranking of the ddox pages in search engines because of 
those single pages, more static content and meta information.

To quote Adam [3]:


 ddox got a decent go up to here.
 But then we need to decide what's next - a clear goal, 
 including a due date, gets us all aligned and removes a lot of 
 the uncertainty on the author's side; it is some reassurance 
 that they aren't wasting their time, and encourages outside 
 teams to get onboard.


We got the MREF change into Phobos a month ago and Sönke has 
fixed the last blocking bug with ddox (broken source code links) 
a couple of days ago.

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.

Does this sound reasonable to everyone?

[1] https://github.com/dlang/dlang.org/pull/267
[2] http://forum.dlang.org/post/575079DE.2040508 erdani.org
[3] 
http://forum.dlang.org/post/zuzlvgqposlmtgdnxhmb forum.dlang.org
Jun 04 2016
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 06/04/2016 12:10 PM, Seb wrote:

 More than two and half years ago, Sönke added ddox builds for the Phobos
 documentation. We all know that there are many reasons for ddox - being
 able to generate single pages for methods is just one, it also
 eliminates all the JavaScript hacks (e.g. the quickindex menu, anchors,
 ...) that we have added over time to deal with the shortcomings of ddoc.

 This post originates from a recent discussion [2] that showed the higher
 ranking of the ddox pages in search engines because of those single
 pages, more static content and meta information.

 To quote Adam [3]:


 ddox got a decent go up to here.
 But then we need to decide what's next - a clear goal, including a due
 date, gets us all aligned and removes a lot of the uncertainty on the
 author's side; it is some reassurance that they aren't wasting their
 time, and encourages outside teams to get onboard.


 We got the MREF change into Phobos a month ago and Sönke has fixed the
 last blocking bug with ddox (broken source code links) a couple of days
 ago.

 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.

 Does this sound reasonable to everyone?

 [1] https://github.com/dlang/dlang.org/pull/267
 [2] http://forum.dlang.org/post/575079DE.2040508 erdani.org
 [3] http://forum.dlang.org/post/zuzlvgqposlmtgdnxhmb forum.dlang.org


I recall there were a few issues with ddox rendering up until relatively 
recently, have all been fixed?

I don't see these options mutually exclusive, though I do want to make 
ddox the default/preferred rendering if ready. Consider e.g. 
https://www.gnu.org/software/make/manual/ which offers the documentation 
in various formats, including fewer/multiple pages.

Now, I gave myself a few minutes to take a look at ddox:

* http://dlang.org/phobos/ looks nicer than http://dlang.org/library/. 
The intro text is not very important, but the grouping is nice. The 
table vertical split ratio is also nicer.

* I assume the dead links matter will be solved.

* The cheat sheet made sense for the single-page docs but not for the 
new ones. Consider e.g. 
http://dlang.org/library/std/algorithm/comparison.html - it's two tables 
with the same row headings one after another. The information should be 
consolidated in one table (I'm speaking from the user's perspective; I 
know it's hard).

* There are a few formatting issues that I like less in the new docs. 
These are of course fixable with relative ease. Looking at e.g. 
http://dlang.org/library/std/algorithm/comparison/among.html:

** the vertical spacing is generally too fluffy (do we really need 25% 
of the page occupied by Authors and License for _every_ function?)

** Do we need the actual "Prototypes" heading or is it implicit?

** The booktable style is nice for tables that span the entire page 
width; for parameters the boxes at 
http://dlang.org/phobos/std_algorithm_comparison.html#among seem nicer 
to me.

** Do we need the actual heading "Parameters", or it suffices to put 
"Parameter" instead of "Name" in the parameter box heading?

** Examples are nice but again vertical spacing overall and between 
consecutive examples is too large.

** Generally the sentiment of the formatting is "too much foreplay". Get 
to the point already, don't have people scroll through fluff. Relegate 
Authors and License to a small footnote below everything - even after 
disqus.

* The hotlinks to parameters (e.g. "value", "values") seem unnecessary 
unless the synopsis is very long which shouldn't be the case. It's also 
inconsistent - pred is not hotlinked.

* How are we going to deal with links (possibly with hashes) pointing to 
the existing artifacts? Again the simplest way is to keep the old docs 
but just deemphasize them on dlang.org.

* I'd like a "Show entire module documentation as single page" link for 
e.g. http://dlang.org/library/std/algorithm/comparison.html.

* How do we address the ebook/pdf production? Do we continue using ddoc 
or look into a ddox approach?

* Any other extant issues with /library/ (I recall there were a few 
cases in which not all text was rendered)?


Andrei
Jun 04 2016
next sibling parent reply ag0aep6g <anonymous example.com> writes:
On 06/04/2016 07:01 PM, Andrei Alexandrescu wrote:

 * The cheat sheet made sense for the single-page docs but not for the
 new ones. Consider e.g.
 http://dlang.org/library/std/algorithm/comparison.html - it's two tables
 with the same row headings one after another. The information should be
 consolidated in one table (I'm speaking from the user's perspective; I
 know it's hard).


I have a pull request open that addresses the issue:

https://github.com/dlang/phobos/pull/4397

It hides the handcrafted cheat sheets. It's not been pulled yet, because 
the handcrafted cheat sheets may be better than the generated ones.

I haven't been able to figure out how to hide the generated ones. Also, 
the handcrafted ones tend to get outdated which is especially bad with 
DDOX, because you can't just scroll down to it.
Jun 04 2016
parent reply =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 04.06.2016 um 19:18 schrieb ag0aep6g:

 On 06/04/2016 07:01 PM, Andrei Alexandrescu wrote:

 * The cheat sheet made sense for the single-page docs but not for the
 new ones. Consider e.g.
 http://dlang.org/library/std/algorithm/comparison.html - it's two tables
 with the same row headings one after another. The information should be
 consolidated in one table (I'm speaking from the user's perspective; I
 know it's hard).


 I have a pull request open that addresses the issue:

 https://github.com/dlang/phobos/pull/4397

 It hides the handcrafted cheat sheets. It's not been pulled yet, because
 the handcrafted cheat sheets may be better than the generated ones.

 I haven't been able to figure out how to hide the generated ones. Also,
 the handcrafted ones tend to get outdated which is especially bad with
 DDOX, because you can't just scroll down to it.


I think ideally we could do something like introducing a special 
"Cheatsheet" section or macro for each function that DDOX could 
aggregate or use instead of the normal short description. Also 
interesting (although less so since we started using sub modules) would 
be to do the same for a group/category that would be used to group 
symbols by other means that simply their type category.

The downside is that the normal Ddoc generated docs couldn't use that 
information to display the overview tables like it does now, so it would 
make most sense to do this after making the switch.
Jun 04 2016
parent ag0aep6g <anonymous example.com> writes:
On 06/04/2016 07:25 PM, Sönke Ludwig wrote:

 I think ideally we could do something like introducing a special
 "Cheatsheet" section or macro for each function that DDOX could
 aggregate or use instead of the normal short description. Also
 interesting (although less so since we started using sub modules) would
 be to do the same for a group/category that would be used to group
 symbols by other means that simply their type category.

 The downside is that the normal Ddoc generated docs couldn't use that
 information to display the overview tables like it does now, so it would
 make most sense to do this after making the switch.


Thinking about this, if the information in the cheat sheet is the most 
helpful, maybe we should be putting exactly that in the summaries of 
things. Meaning, maybe we should change summaries to be one short 
sentence and/or one short example.
Jun 04 2016
prev sibling parent reply =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 04.06.2016 um 19:01 schrieb Andrei Alexandrescu:

 I recall there were a few issues with ddox rendering up until relatively
 recently, have all been fixed?


I think they have. Vladimir has reported a bunch of them over time and 
all of those have been fixed.


 I don't see these options mutually exclusive, though I do want to make
 ddox the default/preferred rendering if ready. Consider e.g.
 https://www.gnu.org/software/make/manual/ which offers the documentation
 in various formats, including fewer/multiple pages.

 Now, I gave myself a few minutes to take a look at ddox:

 * http://dlang.org/phobos/ looks nicer than http://dlang.org/library/.
 The intro text is not very important, but the grouping is nice. The
 table vertical split ratio is also nicer.


This is currently just the generic module overview. We could simply 
replace it by a handcrafted version. Shall I copy the one from /phobos/? 
...or I could also just read the corresponding .ddoc file and render that.


 * I assume the dead links matter will be solved.

 * The cheat sheet made sense for the single-page docs but not for the
 new ones. Consider e.g.
 http://dlang.org/library/std/algorithm/comparison.html - it's two tables
 with the same row headings one after another. The information should be
 consolidated in one table (I'm speaking from the user's perspective; I
 know it's hard).


Leaving that to the other sub thread.


 * There are a few formatting issues that I like less in the new docs.
 These are of course fixable with relative ease. Looking at e.g.
 http://dlang.org/library/std/algorithm/comparison/among.html:

 ** the vertical spacing is generally too fluffy (do we really need 25%
 of the page occupied by Authors and License for _every_ function?)


I intended to tackle that multiple times. Definitely agreed that it 
should be much smaller. On the plus side, it's placed after all of the 
real meat of the page (except for the comments), so it doesn't really do 
any harm.


 ** Do we need the actual "Prototypes" heading or is it implicit?


That's definitely debatable. The first special purpose sections could be 
layed out in a few different ways:

	Primary heading

	brief description

	[prototypes]

	detailed description

	Parameters and other sections

or maybe

	Primary heading

	brief description
	detailed description

	[prototypes]
	[parameters]

or maybe

	Primary heading

	brief description

	[prototypes]
	[parameters]

	detailed description

They all have their pros and cons, and those also depend on what is 
displayed on the parent page. If, for example, the parent page already 
displays the prototypes (which I intended to add in some form), moving 
them further down below the page can make sense. Otherwise it can be 
good to have them near the top, so that the reader gets an early 
impression about the function, before reading through the detailed 
description.


 ** The booktable style is nice for tables that span the entire page
 width; for parameters the boxes at
 http://dlang.org/phobos/std_algorithm_comparison.html#among seem nicer
 to me.


While I don't particularly like those either (but I'll leave the design 
discussion to other people) - I can of course add that right away. I 
just used the default table style there and simply didn't notice the 
style change in /phobos/.


 ** Do we need the actual heading "Parameters", or it suffices to put
 "Parameter" instead of "Name" in the parameter box heading?


Depending on the general page layout we should definitely be able to 
drop the heading.


 ** Examples are nice but again vertical spacing overall and between
 consecutive examples is too large.


Partially agreed, the spacing could indeed be reduced a bit, however, 
one of the big advantages of the single-page layout is that we can use 
more vertical space to give the page more visual structure and thus make 
it easier to scan for a particular section.


 ** Generally the sentiment of the formatting is "too much foreplay". Get
 to the point already, don't have people scroll through fluff. Relegate
 Authors and License to a small footnote below everything - even after
 disqus.


Authors+License sure, but the rest is content, right? Or what else would 
you consider foreplay?


 * The hotlinks to parameters (e.g. "value", "values") seem unnecessary
 unless the synopsis is very long which shouldn't be the case. It's also
 inconsistent - pred is not hotlinked.


You are probably right. Linking to template arguments is currently not 
supported, so dropping parameter linking in general is definitely the 
more comfortable change ;-)


 * How are we going to deal with links (possibly with hashes) pointing to
 the existing artifacts? Again the simplest way is to keep the old docs
 but just deemphasize them on dlang.org.


Ideally we'd set up redirection rules to forward to the new pages, but 
page anchors will be problematic. One idea to solve that would be, 
instead of defining server-side redirection rules, to put some 
JavaScript code inside of the original /phobos/ docs that detects the 
active page anchor and redirects to the proper /library/ sub page.


 * I'd like a "Show entire module documentation as single page" link for
 e.g. http://dlang.org/library/std/algorithm/comparison.html.


So, conceptually a link to /phobos/? What's the motivation for that? Can 
we solve that by adding more information to the module page, possibly 
with a button to show that on-demand?


 * How do we address the ebook/pdf production? Do we continue using ddoc
 or look into a ddox approach?


I'd say we stay with pure Ddoc as long as that is sufficient. It may get 
interesting depending on which way we go with the cheatsheets/overview 
tables.


 * Any other extant issues with /library/ (I recall there were a few
 cases in which not all text was rendered)?


As stated, I think all of the known DDOX/dpl-docs related issues have 
been solved. However, there are still some issues with the JSON output 
of DMD (alias names are not preserved, no documentation inside of 
`static if` and some others). DDOX also has a doc parser based on 
libdparse, which could be a good alternative to work around that. I'll 
have a look at that.

BTW, thanks for taking the time to write this down (again)! I think this 
has also been one of the main issues in the process that there was 
generally very few feedback, I guess mostly because /library/ was quite 
hidden in the "resources" section.

What I think we should do with these issues is to put them into two 
categories: Needs to be solved _before_ or can be solved _after_ the 
switch. Especially those that are present in /phobos/ now are candidates 
for the latter category.
Jun 04 2016
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/4/16 2:23 PM, Sönke Ludwig wrote:

 Am 04.06.2016 um 19:01 schrieb Andrei Alexandrescu:

 I recall there were a few issues with ddox rendering up until relatively
 recently, have all been fixed?


 I think they have. Vladimir has reported a bunch of them over time and
 all of those have been fixed.


Great, thanks.


 * http://dlang.org/phobos/ looks nicer than http://dlang.org/library/.
 The intro text is not very important, but the grouping is nice. The
 table vertical split ratio is also nicer.


 This is currently just the generic module overview. We could simply
 replace it by a handcrafted version. Shall I copy the one from /phobos/?
 ...or I could also just read the corresponding .ddoc file and render that.


Any way you prefer. I'd be fine with copying the manually-crafted table 
from /phobos/, and eliminate or modify the short text preceding it.


 ** the vertical spacing is generally too fluffy (do we really need 25%
 of the page occupied by Authors and License for _every_ function?)


 I intended to tackle that multiple times. Definitely agreed that it
 should be much smaller. On the plus side, it's placed after all of the
 real meat of the page (except for the comments), so it doesn't really do
 any harm.


Cool, thanks. (I think the comments will play a nice role in the future.)


 ** Do we need the actual "Prototypes" heading or is it implicit?


 That's definitely debatable. The first special purpose sections could be
 layed out in a few different ways:


Oh, I meant the actual word. "Prototypes". It takes a lot of vertical 
space and doesn't add information, because obviously what follows are 
the prototypes.


 ** The booktable style is nice for tables that span the entire page
 width; for parameters the boxes at
 http://dlang.org/phobos/std_algorithm_comparison.html#among seem nicer
 to me.


 While I don't particularly like those either (but I'll leave the design
 discussion to other people) - I can of course add that right away. I
 just used the default table style there and simply didn't notice the
 style change in /phobos/.


Makes sense. Any reasonable design should work fine there.


 ** Do we need the actual heading "Parameters", or it suffices to put
 "Parameter" instead of "Name" in the parameter box heading?


 Depending on the general page layout we should definitely be able to
 drop the heading.


Awesome.


 ** Examples are nice but again vertical spacing overall and between
 consecutive examples is too large.


 Partially agreed, the spacing could indeed be reduced a bit, however,
 one of the big advantages of the single-page layout is that we can use
 more vertical space to give the page more visual structure and thus make
 it easier to scan for a particular section.


Reasonable.


 ** Generally the sentiment of the formatting is "too much foreplay". Get
 to the point already, don't have people scroll through fluff. Relegate
 Authors and License to a small footnote below everything - even after
 disqus.


 Authors+License sure, but the rest is content, right? Or what else would
 you consider foreplay?


I'm thinking just rendering the information in an obvious and immediate 
manner that doesn't require scrolling or eyes to jump across the page. 
Consider e.g. https://doc.rust-lang.org/std/boxed/trait.FnBox.html. You 
open the page and boom, you know it's a trait, you see the signature 
(without the need to read "Hey hey hey...! here comes the signature!" 
etc), you see a small yet conspicuous colored box with important 
information about instability, you see the synopsys, and the example is 
right after. No need to scroll! It's all clean, immediate, and 
matter-of-fact, no pomp and circumstance. Imagine that rendered with all 
components delineated by own headings 

introduced<br><br><br>" etc.


 * The hotlinks to parameters (e.g. "value", "values") seem unnecessary
 unless the synopsis is very long which shouldn't be the case. It's also
 inconsistent - pred is not hotlinked.


 You are probably right. Linking to template arguments is currently not
 supported, so dropping parameter linking in general is definitely the
 more comfortable change ;-)


Noice.


 * How are we going to deal with links (possibly with hashes) pointing to
 the existing artifacts? Again the simplest way is to keep the old docs
 but just deemphasize them on dlang.org.


 Ideally we'd set up redirection rules to forward to the new pages, but
 page anchors will be problematic. One idea to solve that would be,
 instead of defining server-side redirection rules, to put some
 JavaScript code inside of the original /phobos/ docs that detects the
 active page anchor and redirects to the proper /library/ sub page.


Seems we can easily defer that if we continue to produce both forms.


 * I'd like a "Show entire module documentation as single page" link for
 e.g. http://dlang.org/library/std/algorithm/comparison.html.


 So, conceptually a link to /phobos/? What's the motivation for that? Can
 we solve that by adding more information to the module page, possibly
 with a button to show that on-demand?


I want to collect statistics on how many people continue to use the 
one-page style. If too few, we can remove that later.

This is no competition and no zero sum game: we have two formats and we 
can leverage that. I and many others prefer page-per-artifact, so 
/library/ is awesome. However there might be a bunch of folks out there 
comfy with the page-per-module, and why hurt them if we needn't.


 * How do we address the ebook/pdf production? Do we continue using ddoc
 or look into a ddox approach?


 I'd say we stay with pure Ddoc as long as that is sufficient. It may get
 interesting depending on which way we go with the cheatsheets/overview
 tables.


OK.


 * Any other extant issues with /library/ (I recall there were a few
 cases in which not all text was rendered)?


 As stated, I think all of the known DDOX/dpl-docs related issues have
 been solved. However, there are still some issues with the JSON output
 of DMD (alias names are not preserved, no documentation inside of
 `static if` and some others). DDOX also has a doc parser based on
 libdparse, which could be a good alternative to work around that. I'll
 have a look at that.


Thanks.


 BTW, thanks for taking the time to write this down (again)! I think this
 has also been one of the main issues in the process that there was
 generally very few feedback, I guess mostly because /library/ was quite
 hidden in the "resources" section.

 What I think we should do with these issues is to put them into two
 categories: Needs to be solved _before_ or can be solved _after_ the
 switch. Especially those that are present in /phobos/ now are candidates
 for the latter category.


Sounds good. I have an honest answer and a manager answer. The honest 
answer is that only the broken links need to be fixed before. The 
manager answer is that everything should be fixed before, because then 
the release creates a forcing function. Otherwise, it could take months 
before any is looked at.


Andrei
Jun 04 2016
prev sibling parent Martin Nowak <code+news.digitalmars dawg.eu> writes:
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)
Jun 10 2016
prev sibling next sibling parent reply Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
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.
Jun 04 2016
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/4/16 2:33 PM, Vladimir Panteleev 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.


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
Jun 04 2016
next sibling parent Seb <seb wilzba.ch> writes:
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
Jun 05 2016
prev sibling parent reply Martin Nowak <code+news.digitalmars dawg.eu> writes:
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
Jun 10 2016
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Jun 10 2016
next sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
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
Jun 10 2016
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Jun 11 2016
parent reply Jonathan M Davis via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Saturday, June 11, 2016 08:45:08 Andrei Alexandrescu via Digitalmars-d 
wrote:

 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


Are _you_ going to spend time going through every single page in the
documentation, looking to see whether someone asked a question and then
reply to them if they did? I'm sure not doing that, and I doubt that many of
us will be. I, for one, rarely even look at the online documentation. I
usually just look at the source code locally. And even if I did look at the
online docs on a regular basis, I'd only see comments on the symbols that I
happened to be looking up, and even then, only if I took the extra time to
look and see whether there were comments. I sure wouldn't be going to the
docs just to see whether someone asked a question - especially when there
so many pages to search through.

I really don't see how it's tractable to have hundreds (if not thousands) of
pages on dlang.org where someone could ask a question. They will
occasionally get an answer, but it's more likely to be from someone else who
doesn't know much than it is from anyone who could give a good answer, since
the folks who are most likely to give good answers won't even be looking.
What's far more likely is that folks will get frustrated, because they asked
a question on the documentation page for a symbol and never got an answer -
or if they did, it was weeks or months later.

- Jonathan M Davis
Jun 11 2016
next sibling parent deed <none none.none> writes:
On Saturday, 11 June 2016 at 12:31:28 UTC, Jonathan M Davis wrote:

 I really don't see how it's tractable to have hundreds (if not 
 thousands) of pages on dlang.org where someone could ask a 
 question.


Wouldn't that be solved by automatically posting the question to 
Learn with a link?
Jun 11 2016
prev sibling next sibling parent Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 06/11/2016 02:31 PM, Jonathan M Davis via Digitalmars-d wrote:

 But the problem is, people will ask questions on these forums, and
 likely will not get answers.




 Why not? -- Andrei




 Are _you_ going to spend time going through every single page in the
 documentation, looking to see whether someone asked a question and then
 reply to them if they did?


There is obviously an overview page
https://disqus.com/home/forums/vibe-d/, but I doubt that we'll actively
administrate it.

Also look at ruby-doc, there is literally zero traffic on the comments.
https://disqus.com/home/forum/ruby-doc/.

Maybe it doesn't hurt much and might help to gather good ideas for some
entities.
Jun 11 2016
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/11/16 12:31 PM, Jonathan M Davis via Digitalmars-d wrote:

 Are_you_  going to spend time going through every single page in the
 documentation, looking to see whether someone asked a question and then
 reply to them if they did?


I get notified by disqus for new posts. The basic idea is if we don't 
prime it we'll never have it. -- Andrei
Jun 11 2016
parent reply Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
On Saturday, 11 June 2016 at 19:20:56 UTC, Andrei Alexandrescu 
wrote:

 On 6/11/16 12:31 PM, Jonathan M Davis via Digitalmars-d wrote:

 Are_you_  going to spend time going through every single page 
 in the
 documentation, looking to see whether someone asked a question 
 and then
 reply to them if they did?


 I get notified by disqus for new posts. The basic idea is if we 
 don't prime it we'll never have it. -- Andrei


I think it wouldn't be too hard to embed DFeed as a comment 
system. What do you think? Then anyone can subscribe to new 
comments through the usual means. The same solution can be 
applied to the blog.

I understand that the current bottleneck is someone adding new 
groups to the NNTP server. Can that be resolved?
Jun 11 2016
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 06/11/2016 03:28 PM, Vladimir Panteleev wrote:

 On Saturday, 11 June 2016 at 19:20:56 UTC, Andrei Alexandrescu wrote:

 On 6/11/16 12:31 PM, Jonathan M Davis via Digitalmars-d wrote:

 Are_you_  going to spend time going through every single page in the
 documentation, looking to see whether someone asked a question and then
 reply to them if they did?


 I get notified by disqus for new posts. The basic idea is if we don't
 prime it we'll never have it. -- Andrei


 I think it wouldn't be too hard to embed DFeed as a comment system. What
 do you think? Then anyone can subscribe to new comments through the
 usual means. The same solution can be applied to the blog.


I'm thinking the line between good dogfooding and NIH is thin. The real 
questions we should be asking ourselves is how well does disqus serve 
our purpose, how good a future it has, and how many folks see it as an 
unpleasant association. Also, how long it would take to adapt DFeed and 
what advantages/liabilities it has.


 I understand that the current bottleneck is someone adding new groups to
 the NNTP server. Can that be resolved?


Walter or Jan should be able to do that. But I'm confused as to how NNTP 
groups would help here.


Andrei
Jun 13 2016
parent reply Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
On Tuesday, 14 June 2016 at 00:31:56 UTC, Andrei Alexandrescu 
wrote:

 Walter or Jan should be able to do that. But I'm confused as to 
 how NNTP groups would help here.


It would allow people to subscribe and reply to comments using 
their newsreader (or by email, if it's also associated with a 
mailing list on Brad's server). It's one of the bigger reasons to 
consider using DFeed.
Jun 13 2016
next sibling parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 6/13/16 9:41 PM, Vladimir Panteleev wrote:

 On Tuesday, 14 June 2016 at 00:31:56 UTC, Andrei Alexandrescu wrote:

 Walter or Jan should be able to do that. But I'm confused as to how
 NNTP groups would help here.


 It would allow people to subscribe and reply to comments using their
 newsreader (or by email, if it's also associated with a mailing list on
 Brad's server). It's one of the bigger reasons to consider using DFeed.


So, this means that someone posts a question to the library's 
std.algorithm.map function (for example), and a newsgroup called 
`library` gets a post with subject like:

[std.algorithm.iteration.map] How does map work?

With replies on newsgroup and email server getting posted back to thread?

If this is the case, I'm all for it. The other features of disqus are 
trivial (up/downvoting mechanism), and not necessary there.

There must be a way, however, to remove posts (at least for dfeed). We 
don't want spam or irrelevant posts lingering there forever.

-Steve
Jun 14 2016
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/13/16 9:41 PM, Vladimir Panteleev wrote:

 On Tuesday, 14 June 2016 at 00:31:56 UTC, Andrei Alexandrescu wrote:

 Walter or Jan should be able to do that. But I'm confused as to how
 NNTP groups would help here.


 It would allow people to subscribe and reply to comments using their
 newsreader (or by email, if it's also associated with a mailing list on
 Brad's server). It's one of the bigger reasons to consider using DFeed.


Aren't the snazzy nice formatting and the display in the page the nicest 
things about on-doc-page comments? Email subscription to such is fine 
but writing via email or NNTP seems a clunky adaptation. BTW does disqus 
allow D syntax coloring? -- Andrei
Jun 14 2016
parent Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
On Tuesday, 14 June 2016 at 13:40:57 UTC, Andrei Alexandrescu 
wrote:

 On 6/13/16 9:41 PM, Vladimir Panteleev wrote:

 On Tuesday, 14 June 2016 at 00:31:56 UTC, Andrei Alexandrescu 
 wrote:

 Walter or Jan should be able to do that. But I'm confused as 
 to how
 NNTP groups would help here.


 It would allow people to subscribe and reply to comments using 
 their
 newsreader (or by email, if it's also associated with a 
 mailing list on
 Brad's server). It's one of the bigger reasons to consider 
 using DFeed.


 Aren't the snazzy nice formatting and the display in the page 
 the nicest things about on-doc-page comments? Email 
 subscription to such is fine but writing via email or NNTP 
 seems a clunky adaptation. BTW does disqus allow D syntax 
 coloring? -- Andrei


Well, Markdown support is on the roadmap, and embedding it into 
the page like Disqus was part of the proposal. Email/NNTP is an 
option, not a requirement :)
Jun 14 2016
prev sibling next sibling parent reply Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
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.
Jun 10 2016
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/11/16 5:16 AM, Vladimir Panteleev wrote:

 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.


I mean ddoc for the standard library code. -- Andrei
Jun 11 2016
parent reply Jonathan M Davis via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Saturday, June 11, 2016 08:48:53 Andrei Alexandrescu via Digitalmars-d 
wrote:

 On 6/11/16 5:16 AM, Vladimir Panteleev wrote:

 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.


 I mean ddoc for the standard library code. -- Andrei


I'm fine with generating the docs with ddox if that works better, but I sure
hope that we're not going to then change how we're doing the actual
documenattion in the source files except that if ddox is smart enough that
we don't need many of the linking macros, then I could see getting rid of
some of those from the docs.

I expect to be able to use version(StdDdoc) and all that and have it do the
right thing with ddox, or the switch to ddox is going to be very annoying
from the standpoint of maintaining the code. However, I would assume that
that's all already been sorted out, since we've been generating the docs
with ddox alongside the normal documentation for some time now.

- Jonathan M Davis
Jun 11 2016
parent Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 06/11/2016 02:24 PM, Jonathan M Davis via Digitalmars-d wrote:

 I'm fine with generating the docs with ddox if that works better, but I sure
 hope that we're not going to then change how we're doing the actual
 documenattion in the source files except that if ddox is smart enough that
 we don't need many of the linking macros, then I could see getting rid of
 some of those from the docs.
 
 I expect to be able to use version(StdDdoc) and all that and have it do the
 right thing with ddox, or the switch to ddox is going to be very annoying
 from the standpoint of maintaining the code. However, I would assume that
 that's all already been sorted out, since we've been generating the docs
 with ddox alongside the normal documentation for some time now.
 
 - Jonathan M Davis


It already does all of that (uses dmd's json output atm.), and of course
has a ddoc macro interpreter built-in (emulating all of it's quirks).
Jun 11 2016
prev sibling parent reply Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 06/10/2016 07:33 PM, Andrei Alexandrescu wrote:

 I'm a bit bummed about that. I like it. Is my understanding incorrect
 that disqus is fairly established by now?


You need to create an account with a pay-by-data company to even post
something.
Jun 11 2016
next sibling parent Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 06/11/2016 03:02 PM, Martin Nowak wrote:

 On 06/10/2016 07:33 PM, Andrei Alexandrescu wrote:

 I'm a bit bummed about that. I like it. Is my understanding incorrect
 that disqus is fairly established by now?


 
 You need to create an account with a pay-by-data company to even post
 something.


I'm mostly out at either of those steps.
Adding some simple comments, really doesn't require so much fanciness,
e.g. this
https://code.dawg.eu/reducing-vibed-turnaround-time-part-1-faster-linking.html
runs on a simple sqlite db (https://github.com/posativ/isso).
Jun 11 2016
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 06/11/2016 09:02 AM, Martin Nowak wrote:

 On 06/10/2016 07:33 PM, Andrei Alexandrescu wrote:

 I'm a bit bummed about that. I like it. Is my understanding incorrect
 that disqus is fairly established by now?


 You need to create an account with a pay-by-data company to even post
 something.


How would we estimate the intersection between folks who do want to ask 
a question, and folks who are ideologically opposed to signing up with 
disqus? Also, we need to be careful about the influence of our personal 
beliefs on the core contributors and the community. -- Andrei
Jun 13 2016
parent reply Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
On Tuesday, 14 June 2016 at 00:27:21 UTC, Andrei Alexandrescu 
wrote:

 How would we estimate the intersection between folks who do 
 want to ask a question, and folks who are ideologically opposed 
 to signing up with disqus? Also, we need to be careful about 
 the influence of our personal beliefs on the core contributors 
 and the community. -- Andrei


Correct me if I'm wrong but the above consideration excludes the 
people who are capable of answering questions.
Jun 13 2016
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 14 June 2016 at 01:42:26 UTC, Vladimir Panteleev 
wrote:

 Correct me if I'm wrong but the above consideration excludes 
 the people who are capable of answering questions.


Yeah, I'm not likely to ever use disqus but if it went through 
the same n.g./mailing list interface at least I'd consider 
talking at times (though I personally think comments in 
documentation should typically be used to just go back and 
improve the documentation rather than making readers actually 
wade through the out-of-date and repetitive comment thread...)
Jun 13 2016
parent Seb <seb wilzba.ch> writes:
On Tuesday, 14 June 2016 at 01:57:44 UTC, Adam D. Ruppe wrote:

 (though I personally think comments in documentation should 
 typically be used to just go back and improve the documentation 
 rather than making readers actually wade through the 
 out-of-date and repetitive comment thread...)


+1
Also I think having a "show in action"/"show usages" button that 
searches for the symbol within the dub universe would be a lot 
more useful.
Jun 14 2016
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/13/16 9:42 PM, Vladimir Panteleev wrote:

 On Tuesday, 14 June 2016 at 00:27:21 UTC, Andrei Alexandrescu wrote:

 How would we estimate the intersection between folks who do want to
 ask a question, and folks who are ideologically opposed to signing up
 with disqus? Also, we need to be careful about the influence of our
 personal beliefs on the core contributors and the community. -- Andrei


 Correct me if I'm wrong but the above consideration excludes the people
 who are capable of answering questions.


Oh, indeed - s/want to ask a question/want to ask or answer a question/

Andrei
Jun 14 2016
prev sibling parent reply Jonathan M Davis via Digitalmars-d <digitalmars-d puremagic.com> writes:
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
Jun 05 2016
parent Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
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".
Jun 05 2016
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 04/06/16 18:10, Seb wrote:


 We got the MREF change into Phobos a month ago and Sönke has fixed the
 last blocking bug with ddox (broken source code links) a couple of days
 ago.


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.

-- 
/Jacob Carlborg
Jun 05 2016
parent Martin Nowak <code+news.digitalmars dawg.eu> writes:
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
Jun 10 2016
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2016-06-04 18:10, Seb wrote:

 More than two and half years ago, Sönke added ddox builds for the Phobos
 documentation. We all know that there are many reasons for ddox - being
 able to generate single pages for methods is just one, it also
 eliminates all the JavaScript hacks (e.g. the quickindex menu, anchors,
 ...) that we have added over time to deal with the shortcomings of ddoc.

 This post originates from a recent discussion [2] that showed the higher
 ranking of the ddox pages in search engines because of those single
 pages, more static content and meta information.

 To quote Adam [3]:


 ddox got a decent go up to here.
 But then we need to decide what's next - a clear goal, including a due
 date, gets us all aligned and removes a lot of the uncertainty on the
 author's side; it is some reassurance that they aren't wasting their
 time, and encourages outside teams to get onboard.


 We got the MREF change into Phobos a month ago and Sönke has fixed the
 last blocking bug with ddox (broken source code links) a couple of days
 ago.


Just found this issue [1], symbols are hyphenated in Safari.

[1] https://github.com/rejectedsoftware/ddox/issues/126

-- 
/Jacob Carlborg
Jun 16 2016