Mockup of my doc dream ideas

[Adam D. Ruppe via Digitalmars-d]

On Friday, 25 December 2015 at 07:41:11 UTC, James Hofmann wrote:
> 1. There's more code than ever and more of a need for code to 
> be well-documented on a conceptual/hand-holding level

Absolutely.

> general idea of fitting the text into a certain container is 
> similar to the API doc tradition of following the 
> class-and-method structure of the code.

I recently went to add some explanation to std.base64 on how to 
get a string out of it since someone asked here. But I actually 
stopped on the official website just because I couldn't find a 
place to put it.

It didn't really fit in base64.d, the existing structure was all 
wrong and it was the wrong level. You can apply the concept using 
base64 but it isn't specific to it. It didn't fit on any of the 
existing pages. And adding a new page was just too painful for 
me. I ended up posting a couple quick sentences to the wiki - not 
even linked from anywhere - then running away. Everybody lost 
just because I felt blocked by the existing structure. (and I 
don't know wiki syntax, I felt like that was another blocker, and 
the dlang.org intralinking situation is terrible too)

This linked page is my dream for a narrow part of the docs: the 
function signature. The whitespace formatting can be worked into 
existing ddoc (I'm angry with existing ddoc and don't want to 
work with it for a while, but it isn't hugely difficult to do and 
I think will be a worthwhile incremental improvement), but my 
other vision is more revolutionary: docs that are written from a 
"how do I do this" viewpoint rather than a "how do I use this".


We still have the "how do I use this" sections, the existing 
pages basically fit that. But they feel written bottom-up. I want 
to do top down.

I've said before that I currently have a contractor working on 
some docs. My instructions for her were simply "write something 
cool in D and document it for future newbies". What she's written 
so far is already very different than what we have, though 
there's still a lot of work to do. (In particular, I'm kinda 
struggling with how much editing I want to do. The point is to 
document a newbie's journey as a guide to other newbies but I 
also see her making a few mistakes that I kinda want to 
correct... but she's learning quite a bit from those mistakes too 
and so could the readers. I hate tutorials that assume everything 
works. Users need to get used to seeing error messages and 
understanding both what they mean and why they are there.)

Once we get started, other things will follow. A friend of mine 
who is new to D just wrote something to save text to a google doc 
this week. The result is useful to him and his work and while it 
isn't super advanced D, the journey would be a good experience 
for others too. What libraries did he use? How did he overcome 
problems?



 From these results-driven narratives, I can go back and start 
linking in more things - related narratives (generic D REST api 
tutorial, JSON use), language feature discussions (what was that 
nested function used in the callback? why use `is null` instead 
of `==`? what's `opIn`?) and idioms, concepts like string 
encoding and type system wrangling, and, of course, library docs 
for the used pieces.

Then link it back to the top level.



Of course, this stuff is a lot of work. I only have so much money 
I can spend on hiring people to work with this for me, and I have 
even less time to spend writing it myself... which is one reason 
why I'm now working on my new automation code.


> The mockup is good in that it cleans up the messy look and feel 
> of the current presentation, and suggests the potential for 
> interactivity. My main concern from a presentation standpoint 
> is high latency, which in these interactive help systems 
> typically comes in the form of slow page loads every time I try 
> to click on something.

That's an issue of implementation. I'm literally in the same room 
as the server TWiD is on so I can't objectively judge its speed, 
but try clicking around the issues here:

http://arsdnet.net/this-week-in-d/dec-20.html

does it respond reasonably well? I made very little effort on 
optimization there... but also kept it simple and did all the 
processing ahead of time. The server hands out pre-built .html.gz 
files on demand, no dynamic parts.

My D doc search engine has dynamic parts: 
http://dpldocs.info/findSkip though I also wrote it with a bit of 
an eye toward efficiency because waiting for docs drives me nuts.

The static parts can all be downloaded in a bundle easily enough. 
Search could be a downloaded program too. Offline docs matter to 
me - I'm not always on the internet either!


> My ideal system would stay one step ahead of me or allow me to 
> stay on the same page as often as possible.

Yes. I'm actually a wee bit split on the one page thing: I like 
having a long, single page with all the info. I just think 
there's a *lot* of advantages to it and actually consider this a 
strength of dlang.org (well, until std.algorithm got split up 
into separate modules. Now it is a pain, and I updated my 
dpldocs.info search engine in response)

Thought, one page per function is ok at times too.

> Semantic documentation source is also one of the rare 
> situations where the XML ecosystem is at its best - XSLT 
> basically exists to declaratively transform semantic markup 
> into formatted presentation, as is done, for example, with 
> DocBook. It wouldn't solve any *particular* problem to target 
> XML, but it would expand people's ability to dream up and 
> implement presentation-side solutions.

Yes, I really wish ddoc just output XML. I've tried to do it 
before using new macros (the default macros are unbelievably bad, 
there's actually decent semantics available through ddoc but they 
are all discarded in the macro phase) but it is a pain and still 
not as detailed as I like!

If you view source on my doc thing, you'll see the beginnings of 
semantic html. I want the identifiers to be called out! (There's 
data-ident="thing" in there now too.) I want the types to have 
metadata.

I'm tempted to make my thing spit out XML and then you'd do the 
rest with XSLT.... but I'm more familiar with html+css than I am 
with xslt so I'm just running with that.... yeah, personal 
limitation there. But semantic html isn't far off from xml anyway.