I’ve ported a couple of intro pages and the current project week page from Slicer wiki to GitHub to show how we could use GitHub for project week page hosting:
EDITED: Changed project name from ProjectWeek into SlicerProjectWeeks EDITED #2: Changed back to ProjectWeek to be inclusive and not focused on a specific platform. EDITED #3: Changed 27 to PW27_2018_Boston
I agree there are many advantages moving away from the wiki. Another one to add to the list is that the process becomes much easier for new users to get an account and contribute content. It happened several times in my memory when users requested wiki accounts, but their request was misplaced, or took too long to approve.
I am struggling to think of disadvantages moving away from the wiki. Perhaps it is the ranking of the existing pages, but I would think that should be resolved with cross-linking.
However, I do not think web page is the right format. I would recommend GitBook. In addition to all of the advantages listed above:
it supports hierarchical organization of the content
content can be edited in a WYSIWYG editor, or directly in Markdown
content can be contributed using either GitHub pull request, or direct edit of the content
See example here: https://qiicr.gitbooks.io/dcmqi-guide/content/. GitBook is also working on a new release, which has (in my view) further streamlined presentation (I have not spent a lot of time investigating the new one, just learned about it this week), see example of the same content on the new platform here: https://qiicr.gitbook.io/dcmqi-guide/.
GitBook is just another html generator/hosting with some nice additional tools and it’s own Markdown flavor. We don’t need to decide on which generator(s) we will use, as we’ll host and edit Markdown files on GitHub anyway.
Last time we checked GitBook was not open to provide their service freely to a large number of users. Has anything changed?
In addition to GitBook, we may consider GitHub pages with various templates, Sphinx/ReadTheDocs, Reveal.js, etc. If we keep things simple then we can probably remain compatible with multiple generators.
You can probably generate a gitbook from the current repository (maybe fork it so that you can experiment with what additional template and other files you have to add).
Any objection in renaming the project to “slicer-project-week” or “SlicerProjectWeek” ?
becomes much easier for new users to get an account and contribute content. It happened several times in my
memory when users requested wiki accounts, but their request was misplaced, or took too long to approve.
For the wiki, I think the idea was to avoid systematically granting access to everyone and explicitly authorize individual. We could change that and it will greatly streamline contribution. I start an other topic to discuss this.
The advantage of Github is that anyone can submit a PR without having anyone explicitly granting access before hand. This will indeed streamline the process.
I actually wanted to rename it to SlicerProjectWeeks but did not have the required access level. I think SlicerProjectWeeks is better than SlicerProjectWeek, as most likely we would host multiple project weeks in the same repository.
We’ll have to see what works well in practice but we could grant write access to each person who submits a pull request with a meaningful project page. With protected branches it is quite safe to grant people write access, as it prevents accidentally overwriting the history. But I would expect that most people would directly edit the pages on the web GUI.
In this page About protected branches - GitHub Docs I read “Can’t be edited or have files uploaded to it from the web”. If it is still like this, then making it a protected branch would make it much harder to edit pages as every change would require a PR or git commit.
I’ve just tried and you can commit directly into a protected branch. I think protected branches got more sophisticated during the past years - you can set it up to only disable force push and delete of the branch.
Pure Markdown will not be sufficient, as we will need to adjust image sizes, insert videos etc. So some flavor of Markdown will be necessary. I don’t think flavors will migrate seamlessly across the various content management services you mentioned.
What do you mean? If you mean large number of collaborators on a single book, then yes - that is constrained. We can apply for free next tier subscription, and that will increase the number of collaborators on a single book to 10. We did this for QIICR.
However, it that is not really critical, since GitBook content can be synchronized with a GitHub repo, which can follow conventional GitHub contribution workflow, and the GitBook automatically updated to track master or another selected branch. I think it should also be possible for other contributors to fork the GitHub repo, make a GitBook from that fork, edit content using visual editor on a specific branch, and then make a pull request back upstream.
I suspect there will be a learning curve for the community no matter which method we pick. Hosting directly from github markdown pages seems the most “standard” and for that reason I think that people will derive the most educational benefit from getting familiar with the github process and github markdown, even if we have to live with some limitations (which so far seem fairly minor for our purposes).
I agree. We can start with plain markdown syntax, it’s simple and compatible with everything. Once we gathered some initial experience, we can make much better informed decisions about how to improve things.
Has anybody talked to @Tina_Kapur? If she is OK with this, too, then we should announce that project pages should be created in this GitHub repository (and update the wiki page so that it points to the GitHub page).
I think these are too long and annoying to type during the week – especially on mobile. So could we please at least set up projectweek.slicer.org or even pw.slicer.org as a redirect?
(I’m not sure why would these semantic URLs be useful? no one is going to remember how to type that, and google doesn’t care anyway )
I support finding some middle ground. My vote goes to PW27_2018_Boston, I think it’s not hard to remember even if you need to type it, and you’ll know when and where that project week was.
I would definitely suggest pw.na-mic.org. Branding project week with a specific platform can create various issues now and especially in the future. We should be inclusive, and think about possible issues down the road. I also think that this kind of decision should involve Ron. Monitoring updates from discourse can be cumbersome, and I suggest we should email Ron directly to seek his input.
