Hi all, I recently moved some documentation to Github and faced the same decision: wiki, gh-pages, or loose markup files? I'd like to offer my thoughts about it.
The problem with Github wikis is that they're either fully public (meaning there's a potential for spam or incorrect content) or closed to collaborators, without the possibility for pull requests. There have been cases of wiki spam on Github: https://groups.google.com/forum/#!topic/bigjob-users/AGZr_UN0RZc http://rants.arantius.com/github-sucks With markup files or gh-pages, anyone with a github account can click "edit", make a change, and Github will automatically fork the repo and create the corresponding pull request. The contributor doesn't even have to know much about git. This is also similar to the old website https://github.com/castleproject/Castleproject.org-Site except there was no inline editor with preview, and HTML instead of a lighter markup language. Of course, this means the maintainer has to review and merge every pull request for documentation, same as with pull requests with code. gh-pages are the most flexible option, you can customize everything and create a better navigation, anyone can create pull requests, and you can bind it to a custom domain. But ultimately I chose loose markup files committed directly in the same branch as the code. This means that code and documentation go always together, and are branched and tagged together (i.e. better versioning). Also, I didn't like any of the available templates and it seems it has a higher maintenance cost (either you go the pure html way, which is more taxing for editors, or use Jekyll, which might fail ( https://help.github.com/articles/pages-don-t-build-unable-to-run-jekyll )). Just my 0.02 Cheers, Mauricio -- Mauricio On Mon, Sep 16, 2013 at 11:45 PM, Krzysztof Koźmic < [email protected]> wrote: > We can keep the old doco and add a message about it being outdated, and > redirect to the new one, or redirect directly. > > How's the rest going? The migration and update? > > Krzysztof > > > On Wednesday, August 21, 2013 2:42:04 PM UTC+10, Aleš Roubíček wrote: >> >> don't forget that stw doc has pretty good ranking in google, we have to >> handle old uris somehow. >> > -- > You received this message because you are subscribed to the Google Groups > "Castle Project Users" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected] > . > Visit this group at http://groups.google.com/group/castle-project-users. > For more options, visit https://groups.google.com/groups/opt_out. > -- You received this message because you are subscribed to the Google Groups "Castle Project Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/castle-project-users. For more options, visit https://groups.google.com/groups/opt_out.
