Mvvmcross: Find alternative to readme.io

[Cheesebaron]

I really don't like how readme.io works. Edit suggestions give strange red buttons when users suggest edits, making them think they cannot submit edits.

Also it is unclear for a user that they already have submitted suggestions, they cannot edit their pending suggestions etc.

I would much prefer something statically generated from some markdown pages which were located on GitHub. Similar to what Cake do with their docs: http://cakebuild.net/docs/

They run on Wyam which runs in azure, which is generated on merges into a branch. This is also very similar to how planetxamarin.com works...

Another issue with readme.io is that the RSS/Atom feed does not render HTML, so markdown is displayed there... Practically no RSS readers understand markdown.

[Cheesebaron]

Possible systems:

• Slate: https://github.com/lord/slate
• Jekyll + collections: http://jekyllrb.com/docs/collections/
• Prometheus: https://github.com/prometheus/docs (kind of looks like what we have now)
• DocNet: https://github.com/FransBouma/DocNet
• Wyam

Simply, what I in the end want is _all_ our documentation editable and available on github. Static pages generated from the docs in the repository.

It doesn't matter whether the static page is hosted somewhere.

To me, Slate and Jekyll sound like very solid bets.

Any opinions?

[martijn00]

Besides that i agree on that editing via Github is a very good suggestion, it should also look good enough. Looking at DocNet that is not a fit, the others could work, but need some love to make it look good.

[MarcBruins]

Github Pages looks like a good choice to me. It automatically deploys and updates your content from github. You are also able to use Jekyll with it and contributors will be able to easily add new content. A good example that uses it is react-native: https://github.com/facebook/react-native/tree/master/docs maps to https://facebook.github.io/react-native/docs. I can give it a shot this weekend

[Cheesebaron]

We did have stuff running here: https://github.com/MvvmCross/mvvmcross.github.io

I can't remember why we went with readme.io instead.

[MarcBruins]

Mm that's weird. Maybe @martijn00 knows?

[MarcBruins]

I'm testing around with Jekyll and github pages. It deploys automatically if there is a file change in the repository. The markup is in markdown format and its pretty easy to setup/expand. It still needs a lot of design love as Martijn mentioned. For me the most important part is good and ease maintainable documentation and this is definitely easy!

The repository has a "docs" folder which has a jekyll website in it. Github pages are turned on on this repository and that's it. Feel free to test it out and send a PR, it will automaticly deploy a new version on the website: https://github.com/MarcBruins/test-gh

Let me know what you guys think!

[martijn00]

Good initiative @MarcBruins! I think there were a couple of things why we didn't use Jekyll last time, Analytics, Design, Google SEO, etc.

Those things should be possible to solve when we put some effort in it i guess.

[Cheesebaron]

Analytics is just a matter of putting in a small tracking script in the source somewhere. I think Jekyll supports GA natively.

Design, just a matter of whipping up some CSS that looks like the readme.io page. We could probably steal most of it from them. Otherwise what they are doing is very standard and shouldn't take long to reimplement in Jekyll.

SEO is supported through: https://github.com/jekyll/jekyll-seo-tag

[MarcBruins]

All those things are possible @martijn00 but it will take some effort exactly like you said! If done right, in the end it should be a very easy maintainable solution! Design is just html css, so will get there eventually. There are some plugins that help with Analytics and SEO and are supported by GH(https://pages.github.com/versions/).

[MarcBruins]

I'll move my repo to https://github.com/MvvmCross/mvvmcross.github.io and continue development there. Let's see where this leads ;)

[martijn00]

I've updated our Jekyll to 1.2.0

[martijn00]

We've moved this to https://github.com/MvvmCross/mvvmcross.github.io/issues/1

[Cheesebaron]

Just FYI. Currently the making of the new home for docs will happen in MvvmCross/mvvmcross-docs and eventually will move into a docs subfolder in this repository.

Since there will be much stuff going on in that repo we don't want to disrupt this repository too much. The plan for the long run is, when the web page is done, there will then be a rule about if a feature is changed in a PR the documentation for that needs to be adjusted accordingly. The same goes for new features in PR's, the author would need to provide documentation for that new feature. This way we ensure that bigger parts of MvvmCross are documented. Currently this process is very disjoint and docs rarely get touched.

We will document this process and adjust the Pull Request templates when that time comes.