Update documentation

bem-archive · Aug 25, 2014 · 7745a16 · 7745a16
1 parent 078e755
commit 7745a16
Show file tree

Hide file tree

Showing 2 changed files with 123 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,12 @@
 # generator-bem-stub [![Build Status](https://travis-ci.org/bem/generator-bem-stub.svg)](https://travis-ci.org/bem/generator-bem-stub) [![Coverage Status](https://img.shields.io/coveralls/bem/generator-bem-stub.svg)](https://coveralls.io/r/bem/generator-bem-stub?branch=master) [![Dependency Status](https://david-dm.org/bem/generator-bem-stub.svg)](https://david-dm.org/bem/generator-bem-stub) [![devDependency Status](https://david-dm.org/bem/generator-bem-stub/dev-status.svg)](https://david-dm.org/bem/generator-bem-stub#info=devDependencies)
 
-A generator of BEM-projects for [Yeoman](http://yeoman.io).
+A generator of [BEM](http://bem.info/) projects for [Yeoman](http://yeoman.io).
+
+## Introduction
+
+There are several assemblers for [BEM](http://bem.info/) projects — [bem-tools](http://bem.info/tools/bem/bem-tools/) and [ENB](https://github.com/enb-make/enb). What does any developer do by starting a new [BEM](http://bem.info/) project? First and foremost, a developer creates a configuration file for an assembler which he is going to use. Unfortunately it is rather time-consuming and and prone to error process both for [bem-tools](http://bem.info/tools/bem/bem-tools/) and [ENB](https://github.com/enb-make/enb).
+
+In order to save time and decrease barrier to entry into the tools for assembly, we decided to create a generator of configuration files which allows a developer to configure the assembly without immersion into tools' **API**. This generator provides you the ability to get the base of [BEM](http://bem.info/) project in few minutes by answering the simple questions.
 
 ## Install
 
@@ -16,19 +22,67 @@ Run:
 $ yo bem-stub
 ```
 
-## Installation of dependencies
+### What does generator-bem-stub support?
 
-```generator-bem-stub``` will install all dependencies after generation of the project.
+* Assemblers:
+ * [bem-tools](http://bem.info/tools/bem/bem-tools/)
+ * [ENB](https://github.com/enb-make/enb)
+* Libraries:
+ * [bem-core](http://bem.info/libs/bem-core/current/)
+ * [bem-components](http://bem.info/libs/bem-components/current/) + design and autoprefixer
+* Platforms:
+ * desktop
+ * touch-pad
+ * touch-phone
+* CSS preprocessors:
+ * [Stylus](https://github.com/LearnBoost/stylus)
+ * [Roole](https://github.com/curvedmark/roole)
+ * [Less](https://github.com/less/less.js)
+* [Autoprefixer](https://github.com/postcss/autoprefixer)
+* Technologies:
+ * [BEMJSON](http://bem.info/technology/bemjson/current/bemjson/)
+ * ie.css
+ * ie6.css
+ * ie7.css
+ * ie8.css
+ * ie9.css
+ * [BEMTREE](http://bem.info/technology/bemtree/current/bemtree/)
+ * node.js
+ * browser.js (only in [ENB](https://github.com/enb-make/enb))
+ * browser.js+bemhtml (only in [bem-tools](http://bem.info/tools/bem/bem-tools/))
+* Template engines:
+ * [BEMHTML](http://bem.info/technology/bemhtml/current/intro/)
+ * [BH](https://github.com/enb-make/bh) (only in [ENB](https://github.com/enb-make/enb))
+* Building of HTML
+* Minimization of separate files (only in [ENB](https://github.com/enb-make/enb))
 
-If you do not want to install dependencies, use the option ```--no-deps```
+### Installation of dependencies
+
+`generator-bem-stub` will install all dependencies and libraries after generation of the project.
+
+If you do not want to install dependencies and libraries, use the option `--skip-install`:
 
 ```bash
-$ yo bem-stub --no-deps
+$ yo bem-stub --skip-install
 ```
 
-## Versions
+### Versions
+
+You can check in the file [app/templates/config.json](https://github.com/bem/generator-bem-stub/blob/master/app/templates/config.json#L2-L20) which versions of the dependencies and libraries `generator-bem-stub` uses.
+
+### Important to know
+
+Many questions in `generator-bem-stub` depend on the previous ones, for example:
+
+* If you have chosen library [bem-components](http://bem.info/libs/bem-components/current/), `generator-bem-stub` will choose [Autoprefixer](https://github.com/postcss/autoprefixer) CSS preprocessor [Stylus](https://github.com/LearnBoost/stylus) as default.
+
+* You can choose template engine [BH](https://github.com/enb-make/bh) only if you have chosen assembler [ENB](https://github.com/enb-make/enb).
+
+* If you have not chosen technology [BEMJSON](http://bem.info/technology/bemjson/current/bemjson/), bundles will be assembled from [BEMDECL](http://bem.info/technology/bemjson/current/bemjson/).
+
+* You can build HTML only if you have chosen technology [BEMJSON](http://bem.info/technology/bemjson/current/bemjson/) and template engine [BEMHTML](http://bem.info/technology/bemhtml/current/intro/) or [BH](https://github.com/enb-make/bh).
 
-You can check in the file ```app/templates/config.json``` which versions of the libraries and dependencies ```generator-bem-stub``` uses or click [here](https://github.com/bem/generator-bem-stub/blob/master/app/templates/config.json#L2-L19).
+* You will be able to choose which separate files to minimize only if you have chosen assembler [ENB](https://github.com/enb-make/enb) ([bem-tools](http://bem.info/tools/bem/bem-tools/) does not support configuration of minimization, all possible files are minimized by [borschik](http://bem.info/tools/optimizers/borschik/)).
 
 ## License
 

diff --git a/README.ru.md b/README.ru.md
@@ -1,6 +1,12 @@
 # generator-bem-stub [![Build Status](https://travis-ci.org/bem/generator-bem-stub.svg)](https://travis-ci.org/bem/generator-bem-stub) [![Coverage Status](https://img.shields.io/coveralls/bem/generator-bem-stub.svg)](https://coveralls.io/r/bem/generator-bem-stub?branch=master) [![Dependency Status](https://david-dm.org/bem/generator-bem-stub.svg)](https://david-dm.org/bem/generator-bem-stub) [![devDependency Status](https://david-dm.org/bem/generator-bem-stub/dev-status.svg)](https://david-dm.org/bem/generator-bem-stub#info=devDependencies)
 
-Генератор БЭМ-проектов на [Yeoman](http://yeoman.io).
+Генератор [БЭМ](http://ru.bem.info/)-проектов на [Yeoman](http://yeoman.io).
+
+## Введение
+
+Существует несколько сборщиков для [БЭМ](http://ru.bem.info/)-проектов — [bem-tools](http://ru.bem.info/tools/bem/bem-tools/) и [ENB](https://github.com/enb-make/enb). Что делает разработчик, начиная новый [БЭМ](http://ru.bem.info/)-проект? В первую очередь разработчик создает конфигурационный файл для сборщика, который он будет использовать. К сожалению, и для [bem-tools](http://ru.bem.info/tools/bem/bem-tools/), и для [ENB](https://github.com/enb-make/enb) — это довольно трудоемкий процесс, в ходе которого часто возникают ошибки.
+
+Для экономии времени и снижения порога вхождения в понимание инструментов для сборки, мы решили создать генератор конфигурационных файлов, который позволяет конфигурировать сборку без погружения в **API** инструментов. Этот генератор предоставляет вам возможность получить базу [БЭМ](http://ru.bem.info/)-проекта за считаные минуты, овтетив на простые вопросы.
 
 ## Установка
 
@@ -16,20 +22,68 @@ $ npm install -g generator-bem-stub
 $ yo bem-stub
 ```
 
-## Установка зависимостей
+### Что поддержиает generator-bem-stub?
 
-```generator-bem-stub``` установит все зависимости после генерации проекта.
+* Сборщики:
+ * [bem-tools](http://ru.bem.info/tools/bem/bem-tools/)
+ * [ENB](https://github.com/enb-make/enb)
+* Библиотеки:
+ * [bem-core](http://ru.bem.info/libs/bem-core/current/)
+ * [bem-components](http://ru.bem.info/libs/bem-components/current/) + design and autoprefixer
+* Платформы:
+ * desktop
+ * touch-pad
+ * touch-phone
+* CSS-препроцессоры:
+ * [Stylus](https://github.com/LearnBoost/stylus)
+ * [Roole](https://github.com/curvedmark/roole)
+ * [Less](https://github.com/less/less.js)
+* [Autoprefixer](https://github.com/postcss/autoprefixer)
+* Технологии:
+ * [BEMJSON](http://ru.bem.info/technology/bemjson/current/bemjson/)
+ * ie.css
+ * ie6.css
+ * ie7.css
+ * ie8.css
+ * ie9.css
+ * [BEMTREE](http://ru.bem.info/technology/bemtree/current/bemtree/)
+ * node.js
+ * browser.js (доступна только в [ENB](https://github.com/enb-make/enb))
+ * browser.js+bemhtml (доступна только в [bem-tools](http://ru.bem.info/tools/bem/bem-tools/))
+* Шаблонизаторы:
+ * [BEMHTML](http://ru.bem.info/technology/bemhtml/current/intro/)
+ * [BH](https://github.com/enb-make/bh) (доступен только в [ENB](https://github.com/enb-make/enb))
+* Сборка HTML
+* Минимизиция отдельных файлов (доступна только в [ENB](https://github.com/enb-make/enb))
 
-Чтобы не устанавливать зависимости, используйте опцию ```--no-deps```:
+### Установка зависимостей
+
+`generator-bem-stub` установит все зависимости и библиотеки после генерации проекта.
+
+Чтобы не устанавливать зависимости и библиотеки, используйте опцию `--skip-install`:
 
 ```bash
-$ yo bem-stub --no-deps
+$ yo bem-stub --skip-install
 ```
 
-## Версии
+### Версии
+
+Вы можете посмотреть в файле [app/templates/config.json](https://github.com/bem/generator-bem-stub/blob/master/app/templates/config.json#L2-L20), какие версии зависимостей и библиотек использует `generator-bem-stub`.
+
+### Важно знать
+
+Многие вопросы в `generator-bem-stub` зависят друг от друга, например:
+
+* Если вы выбрали библиотеку [bem-components](http://ru.bem.info/libs/bem-components/current/), `generator-bem-stub` выберет [Autoprefixer](https://github.com/postcss/autoprefixer) и CSS-препроцессор [Stylus](https://github.com/LearnBoost/stylus) по умолчанию.
+
+* Возможность использования [BH](https://github.com/enb-make/bh)-шаблонизатора появляется только при выборе сборщика [ENB](https://github.com/enb-make/enb).
+
+* Бандлы будут собираться из [BEMDECL](http://ru.bem.info/technology/bemjson/current/bemjson/), если вы не выбрали технологию [BEMJSON](http://ru.bem.info/technology/bemjson/current/bemjson/).
+
+* Вы можете собирать HTML, только если выбрали технологию [BEMJSON](http://ru.bem.info/technology/bemjson/current/bemjson/) и шаблонизатор [BEMHTML](http://ru.bem.info/technology/bemhtml/current/intro/) или [BH](https://github.com/enb-make/bh).
 
-Вы можете посмотреть в файле ```app/templates/config.json```, какие версии библиотек и зависимостей использует ```generator-bem-stub``` или перейдите по [ссылке](https://github.com/bem/generator-bem-stub/blob/master/app/templates/config.json#L2-L19).
+* У вас будет возможность выбрать, какие конкретно файлы минимизировать, только если вы выбрали сборщик [ENB](https://github.com/enb-make/enb) ([bem-tools](http://ru.bem.info/tools/bem/bem-tools/) не представляет возможность конфигурировать минимизацию файлов, все возможные файлы минимизируются с помощью [borschik](http://ru.bem.info/tools/optimizers/borschik/)).
 
 ## Лицензия
 
-[MIT License](http://en.wikipedia.org/wiki/MIT_License)
+[Лицензия MIT](https://ru.wikipedia.org/wiki/Лицензия_MIT)