Matthew,
Food for thought -- so here’s a bit of thinking out loud.
On Tuesday, April 25, 2017 at 3:42:32 AM UTC+1, Matthew Butterick wrote:
> Instead of a wiki, perhaps consider collecting demo code samples into
> a new Racket package & adding explanations via Scribble docs. In turn,
> these will be automatically published at docs.racket-lang.org.
Not a bad idea at all. There are a few content management issues that
need to be considered:
1 Volume: there are 932 tasks implemented on Rosetta Code; all of
which have some value. Since I have contributed a fair number of
these, I know that there is a good amount of time required to just
review each of these pages. A lot of effort would be involved in
cherry-picking tasks for “special treatment”. So the first pass would
be to download as much as I can and (this is what I tend to do when I
panic) stick it between <pre/> tags.
2 Quality: see above regards the <pre/> tags. Once the examples are collected
they will need some improvement:
- task descriptions need to be wikitext->scribbled
- the prose of the task descriptions need to be edited
- the Racket itself needs to be sanitised. Some of it is a bit
minimalist referring back to the original implementation in another
language which *is* properly documented
- if we’re going for bonus points, it needs chunking down
- and maybe even (provide’ing) if some of this is to be of immediate
use
- other meta-data like tagging and proper attribution need to be added
Until all of these quality issues are addressed, we have something
kicking about in the Racket documentation that is less than we expect.
An ugly-examples package could resolve that.
3 Synchronisation: since I'm considering scraping code and “task”
descriptions from external sources; there needs to be an ability to
ensure that both the local and original versions are kept consistent.
If only by flagging that they are not. Although this could be yet more
meta-data.
A question: does scribble or Racket documentation system have a place
for meta-data. I would want to tag examples as “string”, “algorithm”,
“string algorithm”. Otherwise a thousand tasks will be impossible to
search.
- Off the back of that; if there are all these new pages to search,
would this also make the current documentation search overwhelmingly
cluttered? (There could be an index page for each tag, I suppose, so
there would just be a “String Examples” page)
Whether these can be fully addressed using git, or whether some
“third-party” collaborative effort system is needed (i.e. a wiki or
workflow system that will do the heavy lifting of the above) just to get
a handle on this; one would want to explore.
That said, the evidence of the current Racket documentation seems to be
that once quality documentation (and code) is in git, it is well
curated. My problem is just getting there.
> For instance:
>
> http://docs.racket-lang.org/aoc-racket/
>
> Bonus points for using `scribble/lp`.
I suspect I will go for an intermediate language. The chance of falling
on a format that does what is needed first time round is slim; and if,
for example, I need the description moving below the code -- much better
that it is done in a template. But LP is good.
There is another approach I have read of
“Code Guide” http://natpryce.com/articles/000798.html:
> Code Guide is a kind of opposite of Literate Programming.
Fascinating little experiment. But LP, being not-so-interactive can be
printed onto paper.
I’m kinda seeing why this in the “Larger Projects” section.
Tim Brown
--
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.
