Mockup of my doc dream ideas

[James Hofmann via Digitalmars-d]

On Friday, 25 December 2015 at 05:06:47 UTC, Adam D. Ruppe wrote:
> Next, observe the highlighted words... and go ahead and try to 
> click on them. Oh snap! They are links to the language features 
> used. This is the web, let's link all over the place. I want to 
> have relevant conceptual overviews available one click away on 
> every function.

Before I get to remarks about this demo, I'd like to connect the 
D doc situation with the current state of technical writing as I 
understand it(it's something I'm moving towards professionally). 
There's a set of trends I've identified in my survey of the 
landscape:

1. There's more code than ever and more of a need for code to be 
well-documented on a conceptual/hand-holding level, as well as 
the minimal "turn comments into docs" situation. "User manuals" 
are out - everyone wants easy UX - but "API docs" are in.
2. A shift away from proprietary tools like Word or Adobe 
Framemaker towards a heterogenous, open-format ecosystem - e.g. 
conversion tools like pandoc are important now.
3. "Topic-based authoring". This is mainly led by the DITA 
format, which imposes a particular *model* for how the 
documentation is laid out and how pieces of information may be 
related, vs. the more free-form linkage of a wiki or the linear 
text of traditional books. You typically see these topic-based 
systems appear in big enterprisey application software, but the 
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.
4. A default approach that uses lighter markup like Markdown or 
wiki text in order to minimize the barriers to entry. "Heavy" 
formats like DocBook add friction to the prose-writing process, 
even though they're necessary once you pile on enough features. 
Authors may write in one and convert to the other.

The ideal documentation system for D addresses each of these - 
dedicated authors who are primarily adding prose text, a variety 
of output formats, models for defining code/data/textual 
relationships, and low friction inputs.

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. My ideal system would stay one step ahead of me or 
allow me to stay on the same page as often as possible. Options 
for offline docs also usually fix the problem.

There is also a pretty good conceptual base in the existing ddoc 
system w/r to its goal of extending documentation comments. Its 
defaults are biased towards HTML presentation, which is OK, 
albeit not as trendy as Markdown.

What ddoc misses, though, is strong capability to invert the 
semantics towards prose-first - for example, if I wanted to write 
a very extensive tutorial that discusses a large codebase or how 
the codebase changes over time, then I'd write prose first, but 
reference an annotated version of the codebase so that I can call 
out specific parts of it. This is something that could be 
realized with a crude, hand-rolled system to extract the code and 
inline it, but it would most likely give up the semantic 
possibilities; I'd end up only having some syntax highlighting 
and not be able to let the reader click on the source and see the 
file in context, link function name callouts to their API 
documentation, etc.

One way to start seriously addressing all of these various issues 
is to export an annotated, pre-highlighted D source file with 
metadata, which could then be slurped up and processed again into 
an interactive API doc, a prose text, presentation slides, etc. 
This work can be seen as a two-parter: parsing the code and 
emitting useful, easily processed data - and then making default 
presentation of that data good, so that minimal effort is still 
rewarded. It's conceptually similar to the problem space of IDE 
integration, where different IDEs may want to query the source in 
different ways.

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.