I was wondering similar things, a few weeks ago. :)
https://groups.google.com/forum/#!topic/racket-users/MSeP8Fxt-0A
IIRC, Java had HTML-based API docs from `javadoc` from the start
(mid-1990s). (Lisps, Perl, and comment-extracting tools for other
languages did some kind of embedded documentation before Java, but I'd
say Java made it mainstream.) When I moved from Java to Scheme, around
2000, one of the first things I did was made and use a somewhat similar
embedded doc tool, based on three-semicolons and Texinfo. Later, once
Scribble happened, I changed the tool to generate Scribble, and
eventually I wrote a new tool to make Scribble the embedded
documentation language. Now, based on experience with that, and due to
Racket changes like the new package system, I'm at the point of wanting
to make a different tool and documentation format -- but, before I write
my 4th embedded documentation tool, I'd like to know what I could get
people to actually use, when I can't just tell them what they want.
(On telling people what they want... I'd started a book for industry
practitioners, which would teach experienced developers new to Racket a
particular way to use Racket, and basically make a lot of prescriptions,
like "this is how you start a project", "this is how you think of
modularity and reuse", "this is how you make a reusable procedure", and
"this is how you think of versioning". I think there's a brief window
of receptiveness, before people get committed to ways of thinking and
doing things. Especially contemporary Web programmers, who will do
whatever you tell them, as long as they don't think they already
understand it. I'd planned to take advantage of this, to bend everyone
to my will, and have everyone writing their code with a suite of good
practices, from the start. And then, once it's too late, I'd suddenly
spring on them that, all this time, the process was also designed to
support good open source sharing practices, with very little effort or
encumbrance. Daniel-san, show me paint fence. Alas, paying work and
some changes to Racket meant I just didn't have time to finish the
book. Today, I'd have to rethink some practices and make new supporting
tools, in light of changes to Racket and to industry conventions. Two
things that would definitely stay the same with my book, however: I
would emphasize embedded documentation, and I would cage Randall Munroe
in my basement until he drew all the illustrations for my book.)
--
You received this message because you are subscribed to the Google Groups "Racket
Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
