Re: Any work on demo.racket-lang.org?

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+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/[email protected]
For more options, visit https://groups.google.com/d/optout.