Overhauling the GitHub Wiki

Crystal Contrib
1

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
2

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

1 Like
3

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 :|

4

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.

5

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:

6

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