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.
