On 12/17/2015 11:43 AM, Adam D. Ruppe wrote:
> On Thursday, 17 December 2015 at 19:27:56 UTC, Walter Bright wrote:
>> 3. to find out what LREF does:
>>
>>     grep LREF *.ddoc
>
> So, you're working on Phobos and see a LREF macro.
>
> me@arsd:~/d/dmd2/src/phobos$ grep -R LREF *.ddoc
> me@arsd:~/d/dmd2/src/phobos$
>
> ....where is it?
>
> I happen to know it is hidden in the dlang.org repo, but would someone who saw a
> problem in the Phobos docs know that? They seem to be generated from the source
> code.... except when they aren't.

That has nothing to do with Ddoc, and is more about the organization of the files on github. Switching to another framework does nothing for that.

BTW, when I was working on Phobos docs, Phobos had its own std.ddoc in the Phobos repo.

> You can't assume everybody knows all the institutional knowledge you do!

1. digitalmars.D.learn
2. Linux: locate std.ddoc

On 12/17/15 2:43 PM, Adam D. Ruppe wrote:
> On Thursday, 17 December 2015 at 19:27:56 UTC, Walter Bright wrote:
>> 3. to find out what LREF does:
>>
>>     grep LREF *.ddoc
>
> So, you're working on Phobos and see a LREF macro.
>
> me@arsd:~/d/dmd2/src/phobos$ grep -R LREF *.ddoc
> me@arsd:~/d/dmd2/src/phobos$
>
> ....where is it?
>
> I happen to know it is hidden in the dlang.org repo, but would someone
> who saw a problem in the Phobos docs know that? They seem to be
> generated from the source code.... except when they aren't.
>
> You can't assume everybody knows all the institutional knowledge you do!

A document discussing this kind of stuff would be golden. Maybe a good topic for next week's TWiD? -- Andrei

On Thursday, 17 December 2015 at 19:31:10 UTC, Walter Bright wrote:
> On 12/16/2015 10:47 AM, deadalnix wrote:
>> Honestly for D code itself, ddoc does just fine, but for the website, plain html
>> or some known template format like . This is what people know.
>
>
> I've never heard of .

My feedback: add the ability to edit posts in the forum

On 12/17/2015 4:27 AM, John Colvin wrote:
> The number of macros bothers me, but mostly it's the complete lack of
> documentation and guidelines on where/how to use them*.
> It's pretty unreasonable to expect someone submitting a passing doc fix to
> 1) find where the macros are defined
> 2) decipher them
> 3) use the "right" one**
> It's just too much unpleasant work for people to bother with.
>
> *If there is documentation and guidelines on this and I don't know about it,
> consider what it would be like for someone who doesn't spend many hours a week
> on the various subdomains of dlang.org: it might as well not exist!
>
> **there must be some reasons for the existence of all of those macros, so
> presumably there are good and bad choices for certain situations, even if
> nothing is obviously broken using the bad choice. Sure, we might say "submit
> something naïve and then people will help you fix it", but that's still a
> barrier to entry; 1) how were they supposed to know we felt that way about
> submissions? 2) people don't like looking stupid.

Documentation in the std.ddoc files would certainly help. $(COMMENT this is comment) is a convention that works well. PRs to add explanatory comments are welcome.

On Thursday, 17 December 2015 at 20:04:44 UTC, jmh530 wrote:
> My feedback: add the ability to edit posts in the forum

You can't edit email.

On Thursday, 17 December 2015 at 19:51:19 UTC, Walter Bright wrote:
> That has nothing to do with Ddoc, and is more about the organization of the files on github. Switching to another framework does nothing for that.

Well, I basically agree with that.

I know it is hard to keep track of whose position is what in a thread like this, but my problem isn't with ddoc per se, it is more that the current process is very complicated and pretty opaque.

I have more hatred toward the makefiles than toward the doc format.

> BTW, when I was working on Phobos docs, Phobos had its own std.ddoc in the Phobos repo.

std.ddoc was destroyed ages ago, the file no longer exists!

On Thursday, 17 December 2015 at 19:51:33 UTC, Andrei Alexandrescu wrote:
> A document discussing this kind of stuff would be golden. Maybe a good topic for next week's TWiD? -- Andrei

If someone writes it, certainly, but I barely know it myself. I have only successfully build the dlang.org site locally once and that was after you walked through it and I forgot it all since then (except that I remember all the negative emotion of the process like frustration)

Our documentation is lacking documentation...

BTW, on the topic of TWiD, I actually do write it in DDoc, but there's also a post-processor I run on the generated HTML to make up for the lack of things like indexes and some links, and I still feel it is a bit of a pain to use. Missing parenthesis often leak through to show macros in the end, and having to replace $ in links (your message IDs always have them so when I link to your threads, I do a $ -> $(DOLLAR) find/replace, but gotta be careful to run it only once!)

I'm not unhappy with it and don't want to change it, but I'm not terribly happy with it either and kinda wish I did it differently.

Overall, my feeling is just... meh. Ddoc is good for inline documentation, and it can become awesome if we do a little more work to it (and yes, I might do it myself if I can ever find the time), but for stand-alone pages... meh, it gets the job done, at least with a bit of help.

On Thursday, 17 December 2015 at 19:50:40 UTC, Andrei Alexandrescu wrote:
> On 12/16/15 6:47 PM, BLM768 wrote:
>> On Wednesday, 16 December 2015 at 23:43:41 UTC, BLM768 wrote:
>>> [snip]
>>
>> ...and as I read some older posts, I see that mine is completely
>> redundant. ;)
>>
>> Seriously, though, I'm willing to help prototype something. I've got
>> time before the next semester starts.
>
> If you have some time and motivation to improve the documentation, there's tremendous opportunity for impact. So much low-hanging fruit, all well before we explore switching to a different way of building the site. And whatever improvements you make won't compete with future changes. There's so much opportunity there it hurts. -- Andrei

Yes, I'm kind of disappointed I brought up ddoc in there, because everything has been ignored now, while in there, there are many thing more important than using ddoc or not.

And I'd say there is also way more impact changes to do than cleaning the doc as you mention. Searching the doc is late in the tunnel. Clearing the home page has much higher impact options.

But, to start, let's take action. Andrei, does dlang.org has any kind of analytic setup ? If not, would you mind setting up something as google analytic ? That should give us data on what changes are impactful.

On 12/17/15 4:17 PM, deadalnix wrote:
> But, to start, let's take action. Andrei, does dlang.org has any kind of
> analytic setup ?

We use webalizer. -- Andrei

On Thursday, 17 December 2015 at 22:28:25 UTC, Andrei Alexandrescu wrote:
> On 12/17/15 4:17 PM, deadalnix wrote:
>> But, to start, let's take action. Andrei, does dlang.org has any kind of
>> analytic setup ?
>
> We use webalizer. -- Andrei

I would suggest using something more powerful. Log analysis is one thing, but modern tools can do more.

If you are not comfortable with sending data to google, I suggest using piwik : https://piwik.org/ . Some more setup, but you are 100% in control of the data.