jeremyschlatter/chime

Collaboration on Bel user documentation

Opened this issue · 2 comments

masak commented

Howdy, neighbor! 🤠

I represent the other Bel implementation, nice to meet you. Actually, looking at what you've done, it seems that I'm #2 right now, which is... humbling. Good job. 👍

Anyway, I'd like to approach this in a "rising tide lifts all boats" kind of way — I want to suggest a collaboration over Bel documentation, something that both our projects could benefit from. I'm still working on features and optimization myself, but user documentation has been at the back of my mind, and here's my rough plan:

The Documentation System suggests targeting four different audiences: learners, experienced users, people seeking background and context, and people seeking technical description.

Some rough plans for each of these four audiences follows.

Tutorials (for learners)

One thing which I've already started is to port the Arc tutorial to Bel, appropriately adapted.

Could also write other tutorials, maybe some especially showing off Bel's strengths.

Guides (for experienced users)

Guides are supposed to be goal-oriented. Some ideas so far:

  • How to deal with parameters and signature binding
  • How to create a new special form (with examples)
  • How to work with files
  • How to make a new literal type (adding other conveniences, like comparison, virtual functions, loc functions)

No doubt as Bel gains more interoperability, this list can grow.

Explanation (for people seeking background and context)

A non-exhaustive list of topics:

  • Atoms, lists, and pairs
  • Truth
  • Functions
  • Predicates
  • Characters and strings
  • Bindings and environments
  • Dynamic variables
  • Errors
  • Primitive functions
  • Macros
  • Quasi-quotation
  • Special forms
  • Numbers
  • The Y combinator and recursion
  • Threads and atomic
  • Queues
  • set and other macros on "places"
  • Streams
  • Loops
  • Sorting and comparison functions
  • Files and I/O
  • Arrays
  • Tables
  • Templates and instances
  • The reader
  • The evaluator
  • The printer
  • The places where Bel can be extended

This would also be a good place to link to and compare with various other dialects of Lisp and Scheme.

Reference

Austere and to the point. Basically a restatement of the Bel specification documents, but with pertinent details. (For example, you found that digit returns true values that are not t; I found that the even function is not a "safe" predicate, because it doesn't guard on number. Worse, the bquote macro contains an actual infinite loop.)

A lot of functions internal to the evaluator or reader might never be called in practice from user code — although it might be interesting to override them.

  • Data types
  • Primitive functions
  • Special forms
  • Built-in functions and macros
  • Built-in constants
  • Reader syntax
  • Built-in virtual function types
  • Details of the evaluator
  • Errors (and I have a lot to say about errors, enough for a separate issue)

Summary

Anyway, nice to make your acquaintance, @jeremyschlatter. 🤝 I figure we're in a very small group of people who want to fully implement Bel, and collaborating on documentation would be one way to benefit both us and potential users.

I'm not actually asking you to pitch in much, although knowing that you're onboard would provide me with much-needed motivation. (Writing documentation is a slog.) I am curious what you would consider to be an appropriate place to put the documentation. Currently I've started putting it as .pod files in my repository. I'm open to alternative options — for example, maybe a separate repository makes more sense. I'd like to be able to display the documentation as GitHub pages at some point.

Whatever you think of these plans, expect a bunch of smaller bug reports; I've found some places where our implementations differ.

jeremyschlatter commented

Hi, @masak! Thanks for stopping by :)

Happy to hear you're thinking about documentation. I hadn't given it much attention yet.

I haven't devoted much time to Bel for the past few months, and honestly don't expect that to change in the near future. But if you'd like to start a shared documentation project I'd be happy to at least link to it from here and occasionally contribute to it.

I don't have a strong opinion about where to put it. New GitHub repo seems nice and clean, and I'd be down to set up the GitHub pages config for it.

Whatever you think of these plans, expect a bunch of smaller bug reports; I've found some places where our implementations differ.

Thanks! Cool to have multiple implementations to compare.

masak commented

I haven't devoted much time to Bel for the past few months, and honestly don't expect that to change in the near future.

Belatedly, let me extend my sincerest hope that you and those close to you are OK/safe. This has been quite a year — I understand if open-source hobby projects are not always one's top priority. 😷 Thanks for setting the expectations, and please don't take my unbridled enthusiasm as any kind of request to give of time you don't realistically have.

(Writing this from Guangdong, southern China. We've had our fair share of excitement but we've been relatively lucky. Currently, in the sweltering summer heat, face masks are mostly off.)

New GitHub repo seems nice and clean, and I'd be down to set up the GitHub pages config for it.

I set up a new repo in a new organization — neutral ground — and invited you to it: https://github.com/bel-language/docs

I'll transfer my stubbed documentation structure into this repository later tonight. I will also consider having some kind of rudimentary CI/testing for the repository, to check for broken internal links and orphaned pages.