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.