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?