New Documentation: Book Section

[ibolmo]

Please see the proposed Site Content (Outline).

The Book section is meant as a introduction to MooTools. It's meant to supplement the API references.

I've added a few articles that I think would be helpful for a new user. The articles should provide insight in JavaScript development with MooTools. For example, the DOM section should include things like selectors, dom manipulation, and the other common things one does do on an everyday. We should also talk about advanced topics like toElement in Class (perhaps with a tip or informational block).

[arian]

:+1:

[fakedarren]

@ibolmo: how does this differ from 'tutorials'? Or is it just a different name?

The way I see it 'tutorials' will be all-encompassing - it will be powered by a Solr search, so we can also pull in external links, stuff from our blogs, etc.

We can use the design to 'promote' 'series' of tutorials which would essentially give us a 'book' format - a series of related tutorials.

It would be awesome if people could start creating tickets against the 'tutorial runner' milestone - once we have a big fat list of the kind of content we want, it will be easier for us to plan how we'll structure it.

[ibolmo]

Most tutorials, I assume, will focus on the step by step and not try to be as elaborate as much as a book article.

Tutorial would be, "get to learn about Slick" where as a book article would be "The DOM, how to search for and manipulate elements." Different focus.

Well, the site layout that I added has some of the content. You can already see the structure that we'll use.

Tutorials, to me, are the cookbook area. That fits closer to your concept of a blog series and incorporating them into a website section.

Also, a reminder that we'll want to allow i18n for these articles. If we write the articles (cookbook recipes (tutorials) or book articles) it should be easy to download and add a .es.md or an online interface to add i18n entries. The latter being much more involved.

[fakedarren]

Cool, makes sense. I think we want to do this more as 'promoted' or 'in depth' 'tutorials' vs a different section but we'll see what @nfq thinks from a design point of view.

As far as i18n goes....well, I love the idea and it would be fantastic but it's a concern for me that we already have enough difficulty getting content in English to base decisions around getting translations.

But, saying that, the current planned URL structure would make it trivial to use regex to determine a language - eg

http://mootools.net/learn/my-awesome-cookbook/2    // page 2 of cookbook / tutorial 'My Awesome Cookbook'

http://mootools.net/learn/my-awesome-cookbook/2/es    // Spanish translation

So I guess that it is now more of a decision for @nfq or the community team, how do we want to structure the content. I also guess it will be shaped by the discussions we have around content, at the moment we don't really have a clear list of stuff we want, it's all well and good saying 'we should have a section of easy-to-learn tutorials' but we need that list and to implement it.

But yes I understand the overall differentiation. If you're happy with it please close, if not, let's continue the discussion.

[ibolmo]

Well I'm a little confused on the decision. Are we doing a book section?

Also the url is the right idea, but it's the norm is to have the culture after the absolute /. E.g.

http://mootools.net/en/learn... http://mootools.net/es/learn...

Whether people get involved to the i18n it's supplemental. We'll work on the English version and promote via the web page ("contribute another translation", blog article, and so on) but if no one wants to add more translations, o well. No loss off our back. But it's there for the few that do.

I'll repeat that in my opinion the book content, is pretty solid. Take a look at the layout.

Again, I'm not sure your decision about Tutorials vs Cookbook. In my point of view there's no difference, except for the name.

Clarify some of these, and we can close this.

[fakedarren]

Are we doing a book section?

Yes and no, we're doing a 'learn' section, the ultimate decision is up to @nfq from an Information Architecture point of view what the difference is

Also the url is the right idea, but it's the norm is to have the culture after the absolute /. E.g.

The problem I have with that is that it conflicts with the 'plan' for versions and general site-wide URL structure, eg you want /1.2/docs/ vs /docs/ and adding the language (for something that is an 'awesome to have but less realistic' vs a 'must have' complicates matters unnecessarily in my mind.

I appreciate the content in the wiki page (it's really good and others have found it useful) but in order for it to be discussed properly any content requests must be split into individual 'tickets' so they can be discussed individually.

[arian]

The URLs should be:

:?language/docs/:page/:?version

language and version should be optional. I guess with routhing that shouldn't be too hard to solve?

[ibolmo]

Yes and no, we're doing a 'learn' section, the ultimate decision is up to @nfq from an Information Architecture point of view what the difference is

Guess we'll have to leave this open, until he gives his input.

The problem I have with that is that it conflicts with the 'plan' for versions and general site-wide URL structure

/en/1.2/docs and /en/docs /es/1.2/docs and /es/docs

No problem.

Also for the "current" docs. It's better if we used /en/current/docs. Now, do we want current to mean that it's the master branch or the latest tag?

To me, current should mean the master branch. And for website purposes (links etc.) we should just redirect to the tag: /en/1.4.0/docs

[ibolmo]

@arian for SEO and also for UX it's better to be explicit with the URLs.

For SEO, the crawlers can better parse the urls. Also, since the URLs are explicit there's no confusion between content. If we did /docs which also is the exact content of /en/1.4.0/docs then we're going to confuse the bot, and get penalized.

For Humans, it's so explicit my mom understands the URL: /en/1.4.0/docs english, 1.4.0 docs. As a human, if I want a different version I just change the path accordingly: /es/1.4.0/docs and /es/1.3.2/docs.

If we added a query parameter, we'd have to document some where (wiki, or blog post mention) or people would stumble on a versioned url so that one can understand that you can add a ?version= to get another version.

[fakedarren]

The routing is not hard to solve, no. This discussion is about whether to have a 'book' section (and what that means), not our URL structure. You can have that discussion here (and maybe even contribute some code).

To be clear I am not really up for a discussion yet about i18n. It's great to want that but there are so many things that need to be resolved that are required, outstanding tasks, before we start discussing a nice to have, that we can easily solve in several months if everything goes to plan and everyone puts in the work required.

This thread is about whether we want a separate 'books' section and the difference between that and 'tutorials', if any; and we're waiting on other people's input.