Overhauling the GitHub Wiki

The GitHub Wiki is not very accessible and contains a few hidden treasures that should probably be moved to the website or other places.
As a general knowledge base the wiki is redundant: We have already have the website, language reference etc. I think it could serve best as a kind of internal developer documentation, so resources that are not relevant to the regular Crystal users, but for contributers.

These pages are currently on the wiki:

  • Home: The sections Editor support and CI integrations should be moved to a more public place, perhaps a Tools section on the website?
  • :ok: All required libraries: developer documentation
  • :x: Compiler error messages: Only an obsolete example that doesn’t reproduce anymore → can be removed. (In case it comes up again, StackOverflow would be a better place for this)
  • :ok: Compiler internals: developer documentation
  • Crystal for Rubyists: This could be promoted to a guide (which currently reside inside the language reference)
  • :grey_question: FAQ: could be moved to the website, but I don’t think it’s super relevant, so could be left as is
  • :ok: Merging PRs: developer documentation
  • Metaprogramming Help: similar to Crystal for Rubyists
  • Online playgrounds: Should be moved to the website, maybe a Tools section?
  • :+1: Platform Support: This should loose the draft label and move to a more public place, probably the language reference.
  • :ok: Porting to Windows: developer documentation
  • :grey_question: Roadmap: developer documentation. Could perhaps be more prominent, but for the time being it seems fine.
  • :+1: Static Linking: Should be moved to the language reference, maybe extended as a guide with examples.
  • :x: Threads support: seems obsolete → can be removed
  • Used in production: Needs more visibility, should be moved to the website (Community section?)
10 Likes

I removed two wiki pages because they’re hopelessly outdated:

1 Like

As an aside, for me editing “the wiki” is easily outdated but about 10x easier than editing the git book.
Or maybe .a wikibook would be a nice compromise? Dunno…I’m just pointing out that the gitbook which requires PR’s is 10x harder to contribute to :( at least for me…FWIW :|

That’s kind of expected. The wiki is considered more an internal developer resource while the language reference is public documentation. So naturally there should be a more extensive review process.
The wiki can currently be edited by anyone, even without a notification popping up somewhere. That’s easy for contributions, but not ideal either with respect to maintaining integrity of the contents.

Yeah that makes sense. Just higher barrier to entry as well, since editing md files doesn’t have a built-in preview so is more daunting for newcomers…and github PR’s don’t give easy context (or an easy way to “modify one off changes” tbh) :expressionless: but they do allow for review… :slight_smile:

On the wiki home page I removed the entire Editor Support section (linking to GitHub - veelenga/awesome-crystal: A collection of awesome Crystal libraries, tools, frameworks and software instead) and Crystal Libraries (Shards) section (linking to Community - The Crystal Programming Language). It’s better to have just a single place for such lists.

Also published PRs to move Platform Support (#468) and Static Linking (#469) to crystal-book.

4 Likes