Migrating from ScrewTurn Wiki to GitHub

[Jonathon Rossi]

Hey guys,

Last week I migrated all of the MonoRail content from ScrewTurn Wiki (i.e. http://docs.castleproject.org/MonoRail.*) to GitHub Wiki (https://github.com/castleproject/MonoRail/wiki) as a trial to see whether GitHub Wiki was going to be a good fit for all our documentation.

I migrated our style guide to GitHub just before but did it as a ".md" file in an normal code repo rather than in the GH Wiki:

https://github.com/castleproject/Home/blob/master/CONTRIBUTING.md

Comparing both here are some general notes:

* GitHub Wiki doesn't support pull requests, the only options are write permission for all GitHub users or just organisation members. ".md" files inside the code repo works just normal code for pull requests.

* GH Wiki has no email notifications for changes, however there is an ATOM feed.

* GH Wiki has built-in support for a "_Sidebar.md" page, which is how the sidebar works.

* You can fairly easily upload images to GH Wiki by cloning the git repo and adding them, basically the same as you'd do with a code repo.

* GH Wiki has a friendly page editor because it has a markdown toolbar, however I don't think this is a must.

* Both have a preview mode.

* As a organisation member you can edit a ".md" file and commit it directly from the web browser, no need to go through a PR.

* The diff support in code repos is better than the wiki ones because it can show you changes within a line rather than just the whole line.

* GH Wiki supports links to other wiki pages with the "[[Page Name]]" syntax, .md files must use the normal markdown "[Page Name](Page-Name.md)" syntax.

* GH Wiki only has one copy of the docs, so you don't get different docs in each branch. A good thing and a bad thing.

* Cloning the code repo would give everyone an offline copy of the docs, and it would make it easier for people to contribute to the docs when they send a PR for the code because it could be the same PR.

I'd like a bit of discussion on whether we should use GitHub Wiki or Markdown files in the code repo.

P.S. Don't worry about getting the actual work done, I'm happy to finish the migration.

--

Jono

[Jonathon Rossi]

Another quick difference is that GH Wiki will show blue or red links for the [[Page Name]] syntax depending on whether or not the page exists, just like ScrewTurn and MediaWiki. Clicking a red link will take you to the "new wiki page" page. Markdown files in the code repo will just give you the annoying full screen 404 GitHub page:

https://github.com/castleproject/Home/blob/master/New-Page.md

--

Jono

[Henry Conceição]

Based on your observations, it appears that the md approach will be
manageable/less messy than the wiki one.

Are you using some sort of automation to convert it? Which migration
approach demand less effort?

Cheers,
Henry Conceição

> --
> You received this message because you are subscribed to the Google Groups
> "Castle Project Development List" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to castle-project-d...@googlegroups.com.
> To post to this group, send email to castle-pro...@googlegroups.com.
> Visit this group at http://groups.google.com/group/castle-project-devel.
> For more options, visit https://groups.google.com/d/optout.

[Jonathon Rossi]

Thanks Henry, but which observations specifically? I'm truly divided between the two approaches because they both offer things the other doesn't, and I need convincing :)

I'm only using a basic regex to transform some syntax, the rest I'm doing manually because there has been some messy stuff including duplicated content so cleaning that up as I went. Both options are pretty much the same effort as they are both really just md files in a repo.

--

Jono

[Henry Conceição]

As I see, the choice is between a very open approach (opening a wiki
for all github users, otherwise we won't be accepting contributors) or
a open, but controlled, way of accepting contributions with the md +
repo pull requests workflow.

Cheers,
Henry Conceição

[Jonathon Rossi]

Thanks, I did wonder whether that would be seen as non-starter issue. The Nancy guys have been following the very open approach from what I've seen without problems:

https://github.com/NancyFx/Nancy/wiki

However, I have liked the way Mono and Azure have "Edit this page on GitHub" on the documentation hosted on their web sites and it allows you to send a PR via GitHub. Not that we have to do the web site bit, but doing it with just .md files is definitely a well known way of contributing to documentation:

https://github.com/mono/website

https://github.com/Azure/azure-content

You are making me lean this way too, but it would be good if others weighed in their opinions, or just their non-opinion since both are better than the ScrewTurn Wiki.