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.
