Which technology should we use for the guide website?

[tmeasday]

My recollection from investigations a few years ago:

1. Jekyll is pretty unmaintained (or at least the version that GH pages supports is old). So trying to do custom stuff like plugins is a pain.
2. Although GH pages gives a really easy way to host static sites, it's also pretty straightforward to use a CI tool like codeship to hook git commits to some other hosting service like heroku.
3. Middleman is another ruby-based static site generator that's much more mature.

@sachag - perhaps you have some thoughts here.

[SachaG]

Yes, I recommend Middleman. It's more flexible than Jekyll, and they have a new version coming out soon.

Or, another approach would be to build a static site builder in Meteor. That's what we did for book.discovermeteor.com, so maybe this would be a good occasion to reuse/improve some of the pieces, especially if you're thinking about leaving the door open to add features like commenting in the future.

[josephdburdick]

Oh my God, please make a static site generator for Meteor! There's also http://Github.com/frozeman/meteor-build-client which is very active.

[stubailo]

I don't think this project should include a custom static site builder for Meteor. We need to find the closest off-the-shelf thing that will work for our needs.

[stubailo]

I was thinking github pages could be the easiest way to get something up to start iterating on content, but in down for middleman if we can set up continuous deployment easily.

[arunoda]

How about using a Meteor app. With that, we have more control. If we built it with React SEO is built in. Otherwise we can use some other service.

We've some great experience with BulletProof Meteor and it was super easy for us to maintain, just because of Meteor.

All the lessons are written in markdown and maintained in a separate repo. Once edited, use a simple shell/node script to update directly the DB.

We don't have any CI stuff, but it's also extremely possible.

[tmeasday]

GH Pages is certainly the easiest way to get started and given it's all markdown with some minor differences in control structures we could start there anyway and focus on content for the first little while.

I think we'll probably run up against it's limitations pretty quickly from experience.

[SachaG]

I think it makes sense to focus on the content first and just have a repo with plain markdown files. We can always decide on how exactly to output them later on.

By the way, this is how we use Middleman to manage our translations: https://www.discovermeteor.com/blog/community-translations-with-github-middleman-codeship-heroku

[arunoda]

Yeah! That's good.

[jesseflorig]

@josephdburdick :+1: if not for this specific use, for use in general.

[stubailo]

@SachaG I think we should just totally rip off your strategy for this :]

[josephdburdick]

Yeah @jesseflorig I think having a static site generator would be awesome. I also agree with @SachaG that for this specific case just doing it all in Markdown is probably best for the cause.

That said, I think it would be an excellent project to try to create a static site generator using the markdown content as a seed to then output as compiled HTML, automatically creating a gh-pages branch ala https://www.npmjs.com/package/gulp-gh-pages so you always have pages generated when you're ready to push to the gh-pages branch.

[rdickert]

I always thought the DM translation strategy was brilliant. Here's another clever infrastructure built on markdown and middleman. The workflow on this is pretty cool and is accessible to less technical contributors.

[frabrunelle]

Hi, I would like to suggest using GitBook as a potential option.

I just noticed that it wasn't listed in the Technology options section of the research doc, but I think it's definitely worth considering.

One of the main advantage is that GitBook comes with a very nice default template and we would be able to start writing the guide without having to choose or build a template.

Here are some examples of projects using GitBook:

• Django Girls Tutorial
• Building Web Apps with Go
• WordPress The Right Way
• Learn JavaScript
• The Sodium crypto library (libsodium)
• Ethereum Frontier Guide
• SAFE Network System Docs (this is the project I work on. We have now migrated to MediaWiki, but it served us well for about a year and we were able to publish the initial version in a very short time)
• GitBook Documentation (obviously :stuck_out_tongue: )

In the links above, I specifically linked to the content of the documentation, but it's also possible to have a landing page. For instance, here is the landing page for the SAFE Network System Docs. And here is a repository containing a few themes that can be used for landing pages. It's also very easy to build a completely custom landing page, as explained in the README.

In addition to being able to customize the landing page, it is possible to add a custom CSS file for the GitBook itself.

And if you need more customization, you can create your own GitBook plugin or find a GitBook plugin that already exists.

gitbook-plugin-edit-link is worth mentioning. It adds "Edit with GitHub" links on every page. It's used in the Django Girls Tutorial for example.

There are also many "nice-to-have" features with GitBook:

• Very easy to output as an ebook (pdf, epub, mobi)
• Multi-Languages
• Search
• GitBook Editor

GitBooks can be easily published using gitbook.com (it's free for open source GitBooks). It can be linked to a GitHub branch so that whenever there is a push on that branch, the GitBook will be updated. It's also possible to set a custom domain.

And since you can get a static website by just running gitbook build, it would also be easy to host it on GitHub pages.

I would personally choose to host it on gitbook.com because I think it would be easier (every time you push to a specific branch (you can choose which one), the book gets updated and it's free so there is really no reason not to use it :stuck_out_tongue: ). In fact, pretty much everyone who makes a GitBook uses gitbook.com to host it (e.g. see this page).

Considering the Meteor guide outlines, I think GitBook would be a great fit because we can create a chapter for each Guide and subchapters for each of the pages in that guide (e.g. 6.1. The security surface area of a Meteor app) and even a third level section if necessary (e.g. 6.1.2. Publications).

Let me know if you have any questions about GitBook and I can do my best to answer them :smile:

I also think Jekyll + GitHub Pages would be a great option, but it would involve spending time on building a good template, which is something that we could always do later and for now I think it could make sense to start with GitBook so we can focus exclusively on the content.

And in terms of Jekyll + GitHub pages, you mention in the research docs that there is "no easy way to look at versions", but in fact, all you have to do is create a folder for each version. This is exactly what Bootstrap does. For instance, you can access the docs for Bootstrap v2.3.2 by going here.

As for Middleman, I think it would be a great solution as well. I personally don't have a lot of experience with it since I tend to use Jekyll + GitHub Pages, but I've looked at its documentation many times and it seems very good.

[SachaG]

GitBook does seem pretty cool too. For what it's worth we're using http://readme.io for the Telescope docs, and it's nice as well. Although probably not adapted for this specific project since they don't let you host your own content.

By the way, the main reason why I was suggesting building a thing in Meteor was to make it possible to tie it with @stubailo's git integration and harmonize all Meteor docs/guides/etc. in a single stack.

[stubailo]

I'd rather change my tutorial thing to spit out static HTML than bring in all of meteor's features just for that. Shouldn't be that hard! I think it would be great to pull the tutorials into this site eventually.

[stubailo]

@frabrunelle wow, the GitBook stuff does look nice! I feel like we will eventually need much more control over the formatting and other features.

I think tomorrow I'm going to put up the first example article and a super basic Jekyll template on GitHub pages so that we can have this discussion (the best tool in the long term) asynchronously with getting started on publishing some content.

[stubailo]

OK after trying to use Jekyll, I've realized that the problem was I hadn't tried Jekyll yet. Let's not use Jekyll. Unless someone can explain how a Ruby static site generator results in a segfault...

[stubailo]

OK in the interest of getting something up ASAP, I set up a default-looking ReadTheDocs site here: http://meteor-guide.readthedocs.org/

Let's keep the conversation about tools open.

[tmeasday]

:+1:

[mitar]

Should we use http://hypothes.is/ for commenting?

[mitar]

What about http://readthedocs.org/? They are great because they provide also nice versioning. You can nicely integrate them with GitHub.

[mrmnmly]

If You're into ruby static generators, check nanoc - pretty easy to maintain on gh-pages, supports markdown etc. And it's pretty customizable too: https://github.com/nanoc/nanoc

[ridxery]

Hey guys, I am assuming that the reason you want static web pages for speed and time-to-market(TTM) purposes but in my humble opinion,you are thinking small because this new guide do have huge potential to be something greater than just static pages. The one of the main reason meteor is getting popular is because of its reactive nature out-of-the-box so, why we are limiting ourselves! Imagine where every user can submit their tutorials/guides/experiences and get a voting system like '9gag' where a new post needs to get XXX amount/percentage likes (and/or approve by a user/moderator with high reputation) in order to list in the featured category(or they call 'hot' in 9gag) and with extra features like Edit/Alter just like stackoverflow where a person with high reputation can edit a post to make it up-to-date or correct the mistakes in it.

I have a solution for speed problem although this solution wont be as fast as serving static pages but it will make it way better than using standard meteor. We can use two types of caching:

1- App caching in the browser for more info: https://atmospherejs.com/meteor/appcache 2- Subscription caching for more info: https://atmospherejs.com/ccorcos/subs-cache

For the tutorials/guides/patterns I say we use WYSIWYG editor adding images/videos/gifs to make tutorial more interactive and beautiful for new meteorites. It's not hard to change already written tutorial from txt you just need to copy and paste it then style it a bit (if you dont want to do that we could use Latex format when committing so we just use latex parser to turn them html format).

Who I am and What I can offer? I am new to meteor community I have been busy last couple of weeks by making tutorials for MeteorJs on youtube and was about to launch my own tutorial website for the same purpose. I can share my repository on github (currently working on private git bitbucket). Currently my website has most of the basic functionalities we need;

User Roles(Basic User, admin etc..) WYSIWYG editor Commenting on posts Admin Panel to manage (posts, users, comments, even front page featured tutorial listing) typeahead search Only three packages were used on the frontend so its easy to everyone understand and improve (bootstrap3 jquery and fontawesome) also, I have clean structure for source files (its not spaghetti code)

ps: this is my opinion and I am willing to help even if i have to finish the website all by myself. however, please dont hesitate to share your negative feedback :) hit me!

[stubailo]

you are thinking small

I think this is 100% intentional - we've tried to think big about these topics before, and they resulted in over-ambitious projects that never got out of the design or initial implementation stage. I think we need to focus on content first. Do you have any examples of systems like the one you have built creating great, consistent, coherent, and opinionated knowledge bases?

I would also encourage you to examine how your project intersects or complements projects like http://www.meteorpedia.com/.

[ridxery]

we've tried to think big about these topics before, and they resulted in over-ambitious projects that never got out of the design or initial implementation stage. I think we need to focus on content first.

You have your reasons I understand it. You have experienced a fail before and this time you want to keep things simple and I agree the part you mentioned MVP for this project is content. I am already at the halfway finishing my own tutorial website with simple functionality and I set goals for myself at like every 20 tutorial release I will update the website. Actually I am going to build this website for myself, so why dont we work as a team? I(anybody else can join) will work on the website and you just keep doing what you are doing, which is producing content/tutorial/guide then we can merge them.

Do you have any examples of systems like the one you have built creating great, consistent, coherent, and opinionated knowledge bases?

No, I dont have anything (in production) to show you yet but everybody start from somewhere right? I can provide every functionality I mentioned in my post but I am not sure if I follow the best/efficient pattern. This is where experienced(those who have meteor apps in production) can make the code more efficient or show me the way. I know agile development and practices. if you have trust issues we can overview the status at the end of every iteration and btw, I am not a newbie in development just never had a chance to have an app in production but I worked in couple of projects before(as freelancer [php-laravel]).

I would also encourage you to examine how your project intersects or complements projects like http://www.meteorpedia.com/.

I took a quick look and it does have some good links but it has minimal visual expression (images,gifs,videos) just like wikipedia. This project can be the one-stop for every meteor developer as the patterns and guides that will shown here get reviewed by the official MDG developers and professionals. In addition to that, imagine collaborating features included in the same website community will love it. I am just stating my opinion as a new member of this community.

[rgoomar]

What about something like siteleaf? They give you a good amount of customization and take in various forms of formatting including markdown.

[rhyslbw]

It'd be handy to have a something that integrates with Slack, although I've yet to find a documentation platform for Space that does. It's the only thing missing from the development workflow, which is a huge bummer since seeing updates to the documentation is valuable in the feed

[stubailo]

It'd be handy to have a something that integrates with Slack

What kind of integration are you looking at?

[rgoomar]

@rhyslbw We could always setup hooks to send a message to Slack after it is updated. The service doesn't necessarily NEED a slack integration imo. In terms of getting this out there and looking nice and manageable, Slack should really be put on the back burner as a nice-to-have.

[rhyslbw]

@stubailo Any changes or new articles as a start. I'll admit the Guide is probably not the best example where this would be valuable, and my comment is more to raise the generic issue of being aware of changes to documentation. For application and package teams depending on Meteor, a feed of changes keep everyone up to speed.

@rgoomar I agree. It's fruitless right now since there's no turnkey integration for a documentation platform, but I just wanted to float the idea for discussion.

[stubailo]

a feed of changes keep everyone up to speed.

Hopefully, this will be the commit log of this repository eventually. And we'll announce major changes through the appropriate channels.

[rhyslbw]

Sure thing

[frabrunelle]

Hey everyone,

I made a comment suggesting GitBook earlier in this issue.

As far as I can see from the latest meeting notes, the website for Meteor Guide will be built with Hexo, which based on the example looks very good!

Anyways, I just thought I would quickly put up a GitBook to show how it could look like. GitBook is not as easy to customized as making something custom with Hexo, but it's very easy to get started with and can be customized in various ways as described in my previous comment. At the very least, it would be better than ReadTheDocs :stuck_out_tongue:

For this example I just did the minimum number of changes required to have a basic GitBook (see this commit).

I've linked my GitHub repository to my Meteor Guide GitBook. You can see the static website here.

I'm not expecting to convince anyone that GitBook is a better alternative. I agree that GitBook is probably not the best fit for the Meteor Guide. I just want to show you how it looks :smiley: (both the static website and the code).

I just searched for meteor on gitbook.com and I found a few GitBooks :smile: For example, this one looks really nice.

Cheers.

[stubailo]

Yep, @yyx990803 has graciously stepped in to build a website for us. He's done almost exactly the same thing before for Vue, so I'm confident he'll do an excellent and fast job of it!