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.

[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

Post by 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"
https://github.com/castleproject/Home/blob/master/CONTRIBUTING.md
* 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

[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

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
https://github.com/castleproject/Home/blob/master/New-Page.md

Post by 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"
https://github.com/castleproject/Home/blob/master/CONTRIBUTING.md
* 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

--
Jono
--
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
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.

Post by 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

Post by Jonathon Rossi
Another quick difference is that GH Wiki will show blue or red links for

the

Post by Jonathon Rossi
[[Page Name]] syntax depending on whether or not the page exists, just

like

Post by Jonathon Rossi
ScrewTurn and MediaWiki. Clicking a red link will take you to the "new

wiki

Post by Jonathon Rossi
page" page. Markdown files in the code repo will just give you the

annoying

Post by Jonathon Rossi
https://github.com/castleproject/Home/blob/master/New-Page.md

Post by Jonathon Rossi
Hey guys,
Last week I migrated all of the MonoRail content from ScrewTurn Wiki

(i.e.

Post by Jonathon Rossi

Post by Jonathon Rossi
http://docs.castleproject.org/MonoRail.*) to GitHub Wiki
(https://github.com/castleproject/MonoRail/wiki) as a trial to see

whether

Post by Jonathon Rossi

Post by Jonathon Rossi
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"
https://github.com/castleproject/Home/blob/master/CONTRIBUTING.md
* GitHub Wiki doesn't support pull requests, the only options are write
permission for all GitHub users or just organisation members. ".md"

files

Post by Jonathon Rossi

Post by Jonathon Rossi
inside the code repo works just normal code for pull requests.
* GH Wiki has no email notifications for changes, however there is an

ATOM

Post by Jonathon Rossi

Post by Jonathon Rossi
feed.
* GH Wiki has built-in support for a "_Sidebar.md" page, which is how

the

Post by Jonathon Rossi

Post by Jonathon Rossi
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)"

Post by Jonathon Rossi

Post by Jonathon Rossi
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

Post by Jonathon Rossi

Post by Jonathon Rossi
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

--
Jono
--
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
To post to this group, send email to
Visit this group at http://groups.google.com/group/castle-project-devel.
For more options, visit https://groups.google.com/d/optout.

--
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
.
Visit this group at http://groups.google.com/group/castle-project-devel.
For more options, visit https://groups.google.com/d/optout.

[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

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.
On Tue, Apr 28, 2015 at 12:39 AM, Henry Conceição

Post by 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

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
https://github.com/castleproject/Home/blob/master/New-Page.md

Post by 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"
https://github.com/castleproject/Home/blob/master/CONTRIBUTING.md
* 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

--
Jono
--
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
To post to this group, send email to
Visit this group at http://groups.google.com/group/castle-project-devel.
For more options, visit https://groups.google.com/d/optout.

--
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
To post to this group, send email to
Visit this group at http://groups.google.com/group/castle-project-devel.
For more options, visit https://groups.google.com/d/optout.

--
Jono
--
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
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, 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.

Post by 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

Post by Jonathon Rossi
Thanks Henry, but which observations specifically? I'm truly divided

between

Post by Jonathon Rossi
the two approaches because they both offer things the other doesn't, and

I

Post by Jonathon Rossi
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

Post by Jonathon Rossi
effort as they are both really just md files in a repo.
On Tue, Apr 28, 2015 at 12:39 AM, Henry Conceição

Post by 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

Post by Jonathon Rossi
Another quick difference is that GH Wiki will show blue or red links

for

Post by Jonathon Rossi

Post by Henry Conceição

Post by Jonathon Rossi
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
https://github.com/castleproject/Home/blob/master/New-Page.md

Post by 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"

Post by Jonathon Rossi

Post by Henry Conceição

Post by Jonathon Rossi

Post by Jonathon Rossi
https://github.com/castleproject/Home/blob/master/CONTRIBUTING.md
* GitHub Wiki doesn't support pull requests, the only options are

write

Post by Jonathon Rossi

Post by Henry Conceição

Post by Jonathon Rossi

Post by Jonathon Rossi
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,

Post by Jonathon Rossi

Post by Henry Conceição

Post by Jonathon Rossi

Post by Jonathon Rossi
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

--
Jono
--
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
To post to this group, send email to
Visit this group at

http://groups.google.com/group/castle-project-devel.

Post by Jonathon Rossi

Post by Henry Conceição

Post by Jonathon Rossi
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google

Groups

Post by Jonathon Rossi

Post by Henry Conceição
"Castle Project Development List" group.
To unsubscribe from this group and stop receiving emails from it, send

an

Post by Jonathon Rossi

Post by Henry Conceição
To post to this group, send email to
Visit this group at http://groups.google.com/group/castle-project-devel

.

Post by Jonathon Rossi

Post by Henry Conceição
For more options, visit https://groups.google.com/d/optout.

--
Jono
--
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
To post to this group, send email to
Visit this group at http://groups.google.com/group/castle-project-devel.
For more options, visit https://groups.google.com/d/optout.

--
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
.
Visit this group at http://groups.google.com/group/castle-project-devel.
For more options, visit https://groups.google.com/d/optout.