Mockup of my doc dream ideas

default0 via Digitalmars-d digitalmars-d at puremagic.com
Fri Dec 25 09:00:05 PST 2015


On Friday, 25 December 2015 at 14:50:06 UTC, Adam D. Ruppe wrote:
> 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".
>

Aren't these usually called tutorials? Or am I misunderstanding 
what you mean here?

>> 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)

This is literally one of the things that bothers me most about 
the documentation. Mostly when I try figure out how to do 
something I use google. Usually google picks out a couple of std 
module documentation pages for search queries I enter and then I 
have to Ctrl+F-guess my way through pages that make my scrollbar 
almost vanish or guess from function names (which are often 
somewhat abstract so it's hard to guess at what functions you 
should really check out). Then when you try to figure out if a 
function does what you want it to or not, often examples are 
missing and reasoning how to use it if it involves templates and 
template constraints isn't always straightforward if you aren't 
too familiar with the language and its idioms (ie: if you're new 
to it and trying to learn).

A single page really detailing what a function does and providing 
an example for how to use it is what I very much prefer.
I may also be a bit odd in this regard, since I use a pretty high 
zoom level in my browser, so scrolling down long pages (or 
navigations, such as the module list of std) is probably much 
more annoying to me than to everyone else (I often also want to 
hop through the documentation, like "oh okay I get how to use 
this function, but lets also check these two other things while 
Im here *scroll scroll scroll scroll*").
Plus I'm probably biased since I'm coming from C# and thus am 
heavily used to the MSDN docs.

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

:-)


More information about the Digitalmars-d mailing list