Provide standalone documentation

[mitar]

We should start providing stand-alone documentation for Blaze. Some ideas:

• API documentation (probably what is currently at http://docs.meteor.com/)
• guide for good patterns (probably what is currently at Meteor guide)
• guide how to contribute
• documentation should be versioned

I like simplicity of Vue documentation.

Probably we could just use CircleCI testing platform to compile also templates and push it to gh-pages branch on every successful test run on master branch. I did something similar Travis CI.

[MiroHibler]

Agree on all accounts. I was wondering if we can just c/p http://docs.meteor.com + Meteor guide?

[mitar]

That could be a good start of content. It would also be good to coordinate a bit with MDG so that we do not fork content, but that move it. And then they pull it or link to it.

[aadamsx]

I like simplicity of Vue documentation.

I agree, their doc layout/format looks great.

Do you think we should have a independent site set up for this like Vue has (for example docs.blazejs.com or blazejs.com/guide) or just a github readme like Autoform?

Would this be community driven documentation (somehow, example, via a github repo dedicated to it)?

[mitar]

Do you think we should have a independent site set up for this like Vue has (for example docs.blazejs.com or blazejs.com/guide) or just a github readme like Autoform?

I would prefer this.

Would this be community driven documentation (somehow, example, via a github repo dedicated to it)?

I would prefer this.

[HenriBeck]

Totally agree with having a better documentation.

Maybe take a look at Google's Material Design documentation beacuse i think they did a great way of structuring and displaying the content.

[aadamsx]

@mitar do "we" have a domain ready to place documentation in, a place for someone to get started on this?

[mitar]

We do: http://blazejs.com/

[aadamsx]

So if I start a site (using Meteor or just static) on my local box and format it like Vue, would I just check this into a github repo somewhere and then someone will upload the source to blazejs.com/guide? How will this work?

And who owns blazejs.com?

[mitar]

So if I start a site (using Meteor) on my local box and format it like Vue, would I just check this into a github repo somewhere and then someone will upload the source to blazejs.com/guide? How will this work?

Hm, I would like that this process is a bit more organized from the content perspective. Because we would probably migrate content from Meteor docs and guide. And I would not want to fork the content and then have two similar, but not exactly the same content, as content progresses.

But yes, you can give it a first try, just so that we have something and can start discussing. Just keep in mind that content wise we might then re-copy new content over. But structure and the interface itself could be already worked on now. So more lorem ipsum style.

Also, do docs have to be an app? Or could be just statically rendered content? I think the latter allows one to simply save it and have it locally as a reference.

And who owns blazejs.com?

I think a community member for now. @MiroHibler knows more.

[MiroHibler]

@voidale owns the domain (and hosting for now).

[markudevelop]

Hey guys awesome, love what you are thinking blaze js documentation finally :) it was missing for really long time even using blaze for so long and I still find some nice techniques/best practices sometimes.

let me know what ever you want/choose we could use the domain

[mitar]

@voidale: Perfect! Great!

[HenriBeck]

Why don't we write the docs in blaze/meteor? This would be a great example that blaze can work for static content too.

We could just have markdown files with the content and get them via http on the client. And use Blaze to show a loading indicator for example.

[mitar]

Why don't we write the docs in blaze/meteor?

Because you have to run an app to be able to read it.

We could create a reader in Blaze. But content should be readable by just opening a file in the browser.

How you can otherwise make a static HTML/PDF/ePub versions?

[mitar]

And use Blaze to show a loading indicator for example.

If it is static page it should probably load fast enough that this would not be necessary.

[HenriBeck]

I find myself often reading thorugh docs/guides when I'm going by train. The Internet is that great in there ;)

I never said it would be static then ;)

[MiroHibler]

It should be an app with live examples/tutorial, like RactiveJS or Meteor Blaze Components ;)

[mitar]

I am completely on board of using Blaze inside docs, but not to render docs. So I would have static content and then something like Blaze jQuery plugin (#21) to render examples.

[MiroHibler]

Here are my thoughts:

1. One place for all (landing page/documentation/examples/tutorial) - I'm assuming that most of future newcomers will not be such tech-savvy (people starting to learn programming/JavaScript, front-end developers broadening interest/knowledge into full-stack apps, etc.) and I want to make it as easy as possible for them to grasp the tech and not having them trying to find their way around the docs dispersed over the wide wide web; in my previous post I forgot to mention Discover Meteor book as an example;
2. "Pure" Blaze - as an example/tutorial/showcase site, we want to show The Power of Blaze - as much as possible built with Blaze itself; by using static content + "helpers" (jQuery plugins and whatnot) we'll probably confuse learners (we can use "helpers" wisely - only where absolutely necessary);
3. CMS - anyone (with certain rights) should be able to CRUD the documentation regardless of their knowledge of versioning software (git), for example lectors, translators(?), etc.; admittedly not quite simple to implement, especially considering migration of current documentation, but doable.

There, that's the general direction we should look towards.

We don't have to wait on MDG for this one, so let's start to build it and we'll iterate on it as we go.

[HenriBeck]

I think we should have content in markdown files as those are easy to edit on github and are nicely formatted on github too

[mitar]

As I mentioned, I disagree that it should be pure Blaze. it is simply hard to do it in pure Blaze. I have tried for http://components.meteor.com/ and you have to do extra effort to escape stuff and so on. It is really not nice. It does not work offline. You cannot convert it to PDF/ePub. It will be hard for people to contribute, people who are still learning Blaze.

I think we should have nice examples in Blaze people can look into. But guide/doc content should not be in Blaze.

I can understand why people think everything in Blaze would be nice, but the most important thing in the computer world is to know which tool is most suited for a task. There is no tool which is perfect for everything. And even Blaze is not perfect for everything. We have to pick those where it is the best and push those. Not try to have Blaze everywhere and then things do not work as nice as they could.

Moreover, we do not need CMS. We should just be able to edit content through GitHub. Why spending resources implementing/working on CMS when we could just reuse systems we have.

[HenriBeck]

Ok, then use Blaze for the other part of the website, so layout, sidebar etc.. and just display a markdown file?

[mitar]

Yes. This is what I would go for. The markdown file could have included examples, which are post-processed by Blaze again or something, though. So we would probably like dynamic examples.

[alexandesigner]

Agree on all accounts. I was wondering if we can just c/p http://docs.meteor.com + Meteor guide?

I organized using the hexo-theme of the meteor, following the principles of the guide, see

also published on my github pages: see, I used a visual identity that I created, but it's nothing official of course :) https://github.com/meteor/blaze/issues/31

Get excited with the work around the blaze.. haha!!

[laosb]

@alexandesigner Good job! So it can be on blazejs.com I think. @voidale What's your opinion?

[laosb]

There're many things to consider:

• Whether we should treat all packages separately, means Blaze.js/Tracker.js/etc or meteor-packages/meteor-community/MeteorCommunity/OurMeteor
• Whether Blaze or any other packages still mainly maintain by MDG
• Whether Blaze or any other packages belongs to meteor-packages/meteor-community/MeteorCommunity/OurMeteor or MDG

@mitar I think we should list all things to decide at one place, so it can be easier for community to discover everything undecided, and say something about.

[mitar]

Backgorund on how currently documentation works: it is still part of the main Meteor documentation through git submodules. We should probably move it to a stand-alone documentation and then get Meteor documentation to link it here.

[mitar]

I would deploy it under http://blazejs.org/docs/ so that we can use the same GitHub hosting. We can use automatic generation of static content in gh-pages branch (this is why I made it a separate branch).

[mitar]

Done. Versioning is tracker under #77.