[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