[gambit-list] Crowdsourcing Gambit documentation

Lassi Kortela lassi at lassi.io
Thu Apr 30 07:54:43 EDT 2020


Currently Gambit documentation exists in:

- the wiki at gambitscheme.org

- the manual in doc/gambit.txi in the gambit repo

- various research papers and presentations

- email messages and github issues

Email and issues are great for getting work done, but document the 
(often messy) development process rather than its result.

In papers and presentations the perspective can be too broad or too deep 
to serve as an effective manual. Lots of comparisons are made to theory 
as well as other systems in the field. That's great for research but is 
usually not actionable information for users.

The wiki is in principle a good middle ground between email and the 
manual with a low barrier to entry, but in practice an organized 
documentation set has not emerged from it. Clojure offers a similar 
example: clojuredocs.org allows user comments on every page, but while 
they are useful they never seem to result in a cohesive documentation 
set even as the site has existed for years. The official documentation 
shown at the top of the page is quite rudimentary and users are left on 
their own to search the comments in case they need more details (as they 
commonly do). EmacsWiki.org is another wiki with a lot of effort put 
into it. While it is (or used to be) very comprehensive and useful, it's 
never quite clear what information is up to date and whether something 
is "official" or simply something that happened to solve particular 
people's problem at the time it was written.

Wikipedia doesn't have much trouble developing wiki pages into readable 
articles, so I wonder whether the lack of convergence in programming 
wikis is idiosyncratic to their target audience. Programmers are one of 
the only populations who are more comfortable working around structured 
systems like Git repos instead of more free-form ones like wikis and 
email. The standard programmer workflow nowadays revolves around Git, so 
anything that is quickly done via Git is easy to add to the daily loop 
with low friction.

To that end, would it make sense if we tried to centralize all Gambit 
documentation into its texinfo manual and try to make that manual really 
comprehensive? It would take some up-front effort: breaking down the 
monolithic texinfo file into smaller portions that are easier to edit; 
integrating existing knowledge from the gambitscheme.org wiki, mailing 
lists and research papers. But it would enable a Git-based workflow 
based around GitHub issues and pull requests for discussing and 
reviewing changes. I don't know about others, but for me that workflow 
has become so second nature that it's often easier to clone a repo and 
send them a PR than make a mental to-do note to return to a task later.

Thoughts?




More information about the Gambit-list mailing list