On Friday, 1 January 2016 at 16:30:44 UTC, Bastiaan Veelo wrote:
> In my eyes there are three important aspects to quality documentation:

Let me summarize the benefits I see in my way for each of these three items:

>  1. Content

For content, I'm making edits based on common questions I see. I've answered like 1/4 of all the D support requests in 2015 myself and there's a lot of patterns there. I'm also talking to new users and watching them code to see what problems they have myself.

Doing these edits on the status quo keeps getting blocked by the overhead... we have a content problem in part because of the process/infrastructure problem.

>  2. Usability (legibility, X-ref, list of contents, indices, searching)

This is what the new generator does by rearranging and formatting the content. There's a new feature: $(REF ), which is a smarter reference than plain text macros allow, and header macros are built-in so the processor understands how to build a table of contents out of them too.

>  3. Maintainability (ease to contribute, legibility in code, intuitive procedures)

Ease and intuition: I'm creating a web interface to drop suggestions and to preview your new articles. You don't have to build the whole site (which also requires git phobos and git dmd...), just upload your new file.

The final thing will still be a github pull request, but for many cases I can help myself by doing it.

Legibility: I'm limiting ddoc macros to keep them simpler to understand. A comprehensive, but limited set of syntax allows you to actually learn it all and use them as you write without worrying about what weird user-defined macros are there or what the difference between XREF and XREF2 is.

Most documentation should use this fancy syntax sparingly.

> there is too much friction that this be done in the official documentation. But if it is too much for Adam, I am not encouraged to even try...

Well, remember that I'm extremely lazy. You should still try it yourself to understand what I mean and see if you agree.

On Wednesday, 30 December 2015 at 23:05:11 UTC, Adam D. Ruppe wrote:
> This huge friction has killed my desire to contribute to Phobos before and it looks like it is again.
>
> the difference is this time, I have my own fork so the community doesn't have to lose out.

Please keep the good work. The current documentation is a mess, but the "heads" can't see it.

I have a lot a free time, I'd already pointed out the error links you gave on the other response, but in fact I'd like to fix by myself, but then I see how hard is the current process that I couldn't go with it.

But currently I'm looking to your project and maybe I could help there.

JohnCK.

On Saturday, 2 January 2016 at 19:31:24 UTC, JohnCK wrote:
> But currently I'm looking to your project and maybe I could help there.

Well, the generator core is almost stable now, so pretty soon we'll be moving on to the other things.

If I can keep up my vacation pace, this would be set in two more weeks, but since I have to go back to real work soon, we're probably more realistically looking at about two months to beta quality. (Though I do feel it is already a lot better than the status quo! It's not like ddoc does inheritance tree walking either.... though one huge advantage of being in dmd is it pretty easily could...)

Here's my todo list:

* link the attributes to explanation pages
* add type class tag to navbar
* fix contract formatting
* show invariants for structs and classes
* parse old-style aliases
* create a package listing
* cross-linking, including inherited members
* implement the "// just docs" thing
* a few syntax changes
* table of contents when inner sections are detected
* UI - auto-scan a directory (currently it loops over args[1..$])
* Template constraint analyzer
* I don't like the module list view yet. I'm surprisingly pretty happy with the overall look though, it is prettier than I expected coming out of me. (It helps that I stole ideas from elsewhere tho.)

Known bugs:
* Throws: section isn't implemented yet
* REF isn't as smart as it could be
* the inline code scanner doesn't run inside macros
* the code is ugly as sin
* DDOC_PSYMBOL ruins my life.
* Overloading of templates with different constraints isn't recognized
* nav doesn't recognize when you are looking at an overload

Ecosystem todo:
* write all the other linked documents explaining language features. I have like a dozen of these linked.
* make the search better
* "introduced in Phobos version" detection
* Auto-link See Also docs for C functions
* The suggestion box and preview uploader. Third party libs can contribute too - we can have a single place to browse D library documentation kinda like Ruby does (except Ruby's docs are horribly awful, we should try to do better).
* Make it obvious how people can contribute
* Package the code for others to use (it will be GPL'd btw, it uses some GPL components)
* Improve Phobos docs to the max using the new system.

On 1/2/16 2:31 PM, JohnCK wrote:
> On Wednesday, 30 December 2015 at 23:05:11 UTC, Adam D. Ruppe wrote:
>> This huge friction has killed my desire to contribute to Phobos before
>> and it looks like it is again.
>>
>> the difference is this time, I have my own fork so the community
>> doesn't have to lose out.
>
> Please keep the good work. The current documentation is a mess, but the
> "heads" can't see it.
>
> I have a lot a free time, I'd already pointed out the error links you
> gave on the other response, but in fact I'd like to fix by myself, but
> then I see how hard is the current process that I couldn't go with it.
>
> But currently I'm looking to your project and maybe I could help there.

A few follow-up questions, all serious:

Do the projected advantages of Adam's project do not include ease of contribution? If so, how?

Would it be productive to reduce friction to contribute to the current two documentation systems we have, instead of coming with a third system that is likely to have its own issues?

What are the exact difficulties of improving the documentation that you just cannot push past in spite of having time and willingness to contribute?


Andrei

On Saturday, 2 January 2016 at 21:06:19 UTC, Adam D. Ruppe wrote:
> * cross-linking, including inherited members

I got this working in simple cases... which happens to include Phobos' std.socket!

http://dpldocs.info/experimental-docs-2/std.socket.UdpSocket.html

I did a major refactoring of the code today to enable moving forward past the block I hit over the weekend. The code is still bad... but not embarrassingly so anymore, and it makes it a LOT easier to work with.

I did step backward a few steps though (the var FIXME in the output is the result of that), but forward many more.


ddox makes an attempt at inheritance linking, but I'm trying to go further. If I'm successful in my dream, it will list overridden methods in the docs nicely too. But that's still a ways away.

First, I need to re-add the features I dropped in the refactoring (compare the above with this: http://dpldocs.info/experimental-docs/std.socket.UdpSocket.html )

On Sunday, 3 January 2016 at 23:16:30 UTC, Andrei Alexandrescu wrote:
> A few follow-up questions, all serious:

Fair enough... but most of the points you're asking they already have been discussed all over the forums, and some in this topic, like those exposed by Adam.

Like I said currently I have free time and sometimes when I find small problems I just say to myself, look I could help on this... but then I remember all the friction.

And again I'm just talking about small things like fixing wrong URLs or add more examples to the functions and so on but the current process isn't easy.

You may think this is another whining but you know that while DDoc's is a great tool for a problem with docs that you had in the past, maybe need to be re-evaluated now. I'm not saying to stop using tomorrow, but finding ways to make things easy, that anyone could help easily with less friction.

JohnCK.

On Sunday, 3 January 2016 at 23:16:30 UTC, Andrei Alexandrescu wrote:
> A few follow-up questions, all serious:

Sorry, I just forgot an important thing. Somewhere in the beginning of this topic, you had advised Adam to put his efforts into another thing, right?

So imagine this with: D vs C++ where someone comes to you and says: Andrei why are you doing this new language, instead, go back to C++ and put these ideas there.

You know many see D as language that has the power/speed C++ but is simpler, right? Maybe the same thing is happening here.

I think you should reflect about this.

JohnCK.

FYI, even now, I hesitate to change links in my Phobos fork because I kinda want to remain ddoc compatible... and I can never remember what macro it is. And I've been kinda deep in this the whole last week.


Anyway, let's get into this:


On Sunday, 3 January 2016 at 23:16:30 UTC, Andrei Alexandrescu wrote:
> Do the projected advantages of Adam's project do not include ease of contribution? If so, how?

1) a massively simplified build. Indeed, I'll make a web form so you don't even have to have dmd installed to make some docs.

This got posted today:
https://issues.dlang.org/show_bug.cgi?id=15516#c2

Two people whose names I recognize who have been with D for a long time didn't know how to add a page to the website. And what they did figure out was a multi step process.

My system already runs a single file or an entire directory and just works. It will never forget a file because you didn't add it to mak/DOCS of win32.mak or anything else.

I'll also make a web form to upload new pages and probably entire projects for automatic processing too.


2) My linking system already works better than ddoc allows. You can reference with a single macro: $(REF some.name). I also keep MREF, XREF, and a few others for legacy phobos+ddoc compatibility, but the user doesn't have to know a hundred obscure macros. (There's about a half-dozen simple ones instead, plus a few thin wrappers over HTML which I might kill but might not since they don't really bother me.)

Combined with the ease of adding all new files, contributors can just link new articles they write to go in depth without worrying about process.



3) I'm also going to make a dynamic webpage once I declare this beta where viewers will be given random pages and asked to eyeball it for me. If they flag it as buggy - with a single click on the page, no bugzilla signups - it'll contact me and I'll work on the bug.

If they want to contribute to content, I can pull up the existing comment source code and present it right there, again likely emailed to me for integration, or the source location can be opened in Phobos for a traditional pull request.

This will encourage crowd sourcing doc bug fixes.


4) I'll never complain about spaces vs tabs, line length, or any other trivial nonsense. If I don't like that stuff, I'll just fix it myself instead of letting the PR wither and die while letting the contributor feel undervalued.

On 2016-01-05 01:23, Adam D. Ruppe wrote:

> ddox makes an attempt at inheritance linking, but I'm trying to go
> further. If I'm successful in my dream, it will list overridden methods
> in the docs nicely too. But that's still a ways away.

I suggest showing only links to inherited members, not the docs for them. I think that the Eclipse Java documentation is pretty good [1], except for its crappy UI surrounding the docs. It actually looks better with JavaScript disabled.

Anyway, it shows inherited fields and methods. For classes it shows known subclasses and for interfaces known implementations.

The Scala docs [2] are pretty good as well. Separates abstract and concrete methods. Separate sections for the different protection levels and so on.

[1] http://help.eclipse.org/luna/topic/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/core/dom/Expression.html

[2] http://www.scala-lang.org/api/current/#scala.collection.Map

-- 
/Jacob Carlborg

On 2016-01-05 01:23, Adam D. Ruppe wrote:

> First, I need to re-add the features I dropped in the refactoring
> (compare the above with this:
> http://dpldocs.info/experimental-docs/std.socket.UdpSocket.html )

"Address" not being cross-linked here [1] while "SocketOSException" is.

[1] http://dpldocs.info/experimental-docs/std.socket.getAddress.html

-- 
/Jacob Carlborg