On Friday, 25 December 2015 at 07:41:11 UTC, James Hofmann wrote:
> On Friday, 25 December 2015 at 05:06:47 UTC, Adam D. Ruppe wrote:

I strongly agree Markdown is simple to use, and well supported. No need to do work that has already been done. Besides, Github is pretty popular nowadays.

assert(false, "jQuery has a really good documentation.");

On Friday, 25 December 2015 at 15:51:02 UTC, rcorre wrote:
> On Friday, 25 December 2015 at 14:24:34 UTC, Bubbasaur wrote:
>>
>> What happens when I see a DOC with comments is that sometimes the comments are more clear than the Doc itself, or there are tips or tricks that was not "well" documented.
>>
>> Bubba.
>
> If the comments are more clear than the Doc, then they should _be_ the doc.

I agree with this. The PHP documentation is a mess because of the comments.

> Similarly, useful tips and tricks should probably be included as doc examples. In other words, I think we should encourage contribution to official documentation rather than dividing between official docs and user comments.

I think there should be link to the wiki for tips and tricks and more examples. Sometimes you don't want 10 examples in the official docs, even if they will help some users. The main reason for using the wiki would be specialized examples.

> This does raise the bar to entry though, so maybe a suggestion box could be a nice middle ground.

Filing a bug is a better approach. It's best to keep everything in one place.

On Friday, 25 December 2015 at 17:00:05 UTC, default0 wrote:
> On Friday, 25 December 2015 at 14:50:06 UTC, Adam D. Ruppe wrote:
> Aren't these usually called tutorials? Or am I misunderstanding what you mean here?
>
> A single page really detailing what a function does and providing an example for how to use it is what I very much prefer.

> Plus I'm probably biased since I'm coming from C# and thus am heavily used to the MSDN docs.
>
>> Thought, one page per function is ok at times too.
>
> :-)

This is exactly how i feel. You might see me as coming too weak because im used to C# and MSDN Docs holding my hand but with the help of those docs and autocompletion, i learned a decent amount of C# in less than 2 weeks without rarely asking anyone for help. This isnt something you could say for C/C++ or even ruby and python.

On Friday, 25 December 2015 at 22:26:46 UTC, bachmeier wrote:
> Filing a bug is a better approach. It's best to keep everything in one place.

Bugzilla sucks hard though, on pretty much every level. It is separate from the page itself, people might not even know it is there, you have to log in, and then fill in a bunch of stuff manually.

On the maintainer side, it is really hard to search, a pain to find new issues that are relevant to you, and it is just separate again from the PR process and all that.

The suggestion box, on the other hand, would immediately alert me, it would tell me what page the suggestion came from, and the user doesn't have to jump through many hoops. Then, I can manage the backend however I like too. Heck, it could even open a bugzilla issue.

On Saturday, 26 December 2015 at 03:01:25 UTC, Israel wrote:
> This is exactly how i feel. You might see me as coming too weak because im used to C# and MSDN Docs holding my hand

If it wasn't for Microsoft documentation (I didn't use MSDN per se, but a downloaded win32.hlp file - I didn't have the Internet at home until the last decade - from the Windows 95 era with basically the same content), I'm not sure I'd know half the stuff I know now.

On Friday, 25 December 2015 at 19:00:13 UTC, karabuta wrote:
> I strongly agree Markdown is simple to use, and well supported.

I don't like Markdown personally, though I don't hate it either. A couple features in it are cool, but most of them are just meh to me and a few of them I actively dislike.

However, the syntax the documentation is written in is of less relative importance to me than the content and the layout. I write ddoc every week and it annoys me a little... and I also think it has fundamental design flaws that put a hard limit on how much it can improve... but it is basically good enough.

I also mostly like writing XML, it really isn't bad!


But you'll notice the "dream doc" mock still had ddoc. Even if I were to change things, I'd change it for my new docs... I wouldn't want to go through and convert all of Phobos. (Besides, I'm not the only consumer of the phobos source.)

On Friday, 25 December 2015 at 17:00:05 UTC, default0 wrote:
> Aren't these usually called tutorials? Or am I misunderstanding what you mean here?

Oh maybe, I've heard "tutorial" used in a lot of contexts and a lot of meanings though, so I wanted to be more specific.

> This is literally one of the things that bothers me most about the documentation. Mostly when I try figure out how to do something I use google.

Google does a really bad job on the D docs... and the D docs don't have enough anchors for it to pick up anyway. (Even if I want to manually share a link, there aren't links to most the ddoc sections! Aaargh!)

But the improved interlinking ideas will help with all of that, single pages or separate pages.

> templates and template constraints isn't always straightforward if you aren't too familiar with the language and its idioms (ie: if you're new to it and trying to learn).


Yeah, I think there's three general levels of users:

1) those who don't speak D-ese at all and need to learn the language. D-ese includes more than D itself, but also phobos idioms, general layout, etc.

These people really need higher level docs to make sense of it. Tutorials and conceptual overviews need to be written with these people in mind.

2) People who are conversational, but not fluent, in D-ese. They can basically get stuff done but don't know it all.

The function-level docs should be good enough for them, but it should translate some of the harder stuff to plain English. Don't ask them to read a constraint mess, just say it in words and in examples.

This is the target audience of the stdlib inline docs IMO. They know how to get there, but then need some assistance bringing it back home.

3) People who are fluent in D-ese. The docs aren't terribly important to them except to quickly refresh themselves. They are fully capable of reading the source, but like the docs for a quick outline.

The actual content isn't really important to these folks, they just want a convenient index.

> Plus I'm probably biased since I'm coming from C# and thus am heavily used to the MSDN docs.

Yeah, MSDN is great, I think it will be my main model.

On Friday, 25 December 2015 at 05:06:47 UTC, Adam D. Ruppe wrote:
> My mock:
> http://arsdnet.net/mydoc.html
>
> Verily, this is the status quo:
> http://dlang.org/phobos/std_algorithm_searching.html#findSkip


Well, the mock is starting to become a reality:

http://dpldocs.info/experimental-docs/std.algorithm.searching.findSkip.html


Though I might be forced to implement ddoc macros. Ugh.
http://dpldocs.info/experimental-docs/std.algorithm.searching.findSkip.html


I also ran my simpledisplay.d through it which also has classes and uses ddoc macros much more sparingly:

http://dpldocs.info/experimental-docs/simpledisplay.html

http://dpldocs.info/experimental-docs/simpledisplay.SimpleWindow.html


And this is a test function:

http://dpldocs.info/experimental-docs/arsd.doc.test.test.html



Still quite a bit to do but it is getting there. I'm using Brian Schott's libdparse to get the source. I want to borrow some of his DCD code to do the scope name lookups and make those dummy links real, and then it is the task of actually formatting the comments and, of course, making sure everything goes through correctly.

On Saturday, 26 December 2015 at 19:56:13 UTC, Adam D. Ruppe wrote:
> http://dpldocs.info/experimental-docs/std.algorithm.searching.findSkip.html


BTW the missing code sample is a documented unittest, which my thing hasn't implemented yet.

On Saturday, 26 December 2015 at 19:56:13 UTC, Adam D. Ruppe wrote:
> Still quite a bit to do but it is getting there. I'm using Brian Schott's libdparse to get the source. I want to borrow some of his DCD code to do the scope name lookups and make those dummy links real, and then it is the task of actually formatting the comments and, of course, making sure everything goes through correctly.

The name lookup code is here: https://github.com/Hackerpilot/dsymbol.

If you haven't seen it already, I recommend that you take a look at this: https://github.com/economicmodeling/harbored