# Hackathon: BEM Documentation team results

Hi everyone,

I can't wait to share my impressions on the past first Hackathon on BEM! It was first hackathon in my life, and I already acted as a mentor. Let me tell you the truth — I liked it a lot :)

And I am going to tell you everything step-by-step.

## Prehistory

First of all, I will tell you about myself:

My name is [Inna Belaya](http://en.bem.info/authors/belaya-inna/), and I manage a team that develops our technical documentation for BEM. Almost a year we, technical writers, together with development team are leading BEM documentation to its bright future. The way is thorny and bumpy, but we try our best :) We write, translate, follow users feedback and move towards being understandable.

When the opportunity to meet in person and even better to work with BEM community developers appeared, I agreed with pleasure. This event allowed us
* To get feedback on current state of the documentation — what developers lack, what might be improved and needed to be improved;
* To improve the documentation and [bem.info](https://en.bem.info) together with the developers from BEM community;
* To set new goals in the future workload.

It is not easy to be a mentor. I needed to work hard before the event in order to understand what problems we need to solve.

I drafted the following:
  * Lack of product information;
  * Huge volumes of the current documentation;
  * Complex, difficult-to-understand language of written documentation that makes understanding of complex technologies even more difficult;
  * Billingualism.

So, these problems were set to priority as possible tasks for hackathon, and
  * To revise **bem.info structure** in order to give complete understanding of BEM methodology, platform – libraries, tools, technologies – and product community, to simplify search and understanding of the information;
  * To develop **basic principles** for providing information on the site;
  * Possibly to **translate missing parts** of the documents.

![](https://img-fotki.yandex.ru/get/15539/44214498.bc/0_9bbeb_1b0515f0_XL.jpg)

## It is time to hack!

### Few common words :)

Hackathon was planned accordingly: all participants meet and get to know each other the day earlier. We had a dinner together and a little tour on Yandex.Moscow. When we meet the next day, we felt comfortable already knowing each other. Everyone was a little nervous because of coming tasks and projects presentations. Greeting speech of [Yelena Jetpyspayeva](https://en.bem.info/authors/jetpyspayeva-yelena/) (known as Mursya) and [Vladimir Grinenko](https://en.bem.info/authors/grinenko-vladimir/) was very heartful and informal and switched everyone to this wave. Positive touch lasted all 48 hours.

### Project presentation and forming the teams

Mentors were supposed to create an idea, form a team and lead it to production. When the registration for hackathon was opened, we could see who and how many developers are interested in the topic. However to know for sure how many of them finally join the team, we could only after the presentation itself. Every mentor had to present his project in any convenient way and compete for the developers with the other mentors. There were no corporate templates or rules how to present, everyone decided for himself. However, all the presentations resulted in interesting and often humorous performances :)

After the presentations there were time for the participants to decide which team to join. Many were in two minds about what group to choose. Because all of the projects were challenging. I was worried, would the developers join my team, would the documentation problems be interesting for the developers. But it ended better then ever, and I finally had a team of:
* [Vitaly Harisov](https://en.bem.info/authors/harisov-vitaly/), who created BEM
* Victoria Fillipova
* [Mikhail Baranov](https://en.bem.info/authors/baranov-mikhail/)

![](https://img-fotki.yandex.ru/get/17934/44214498.bd/0_9bc0a_7c0c5de_XL.jpg)

Once teams were set, everyone get himself a place and started working. Long hours of silence with short friendly breaks on coffeepoints, pizza time and sweets breaks began.

Let me go into details about the place of hackathon: organizers did their best to make it comfortable. Here were working places for everyone taste: openspaces with big marker board walls, small meeting rooms with round tables, bigger rooms, where teams got together to discuss work. Behind glass doors you could oftenly hear lively discussions of the projects. Work was in full swing. And who was tired, could get some privacy in hammock room.

### Team work, tasks, the process

My team chose the big room and shared it with another one. We started our work. I was surprised that documentation team was joined by the developer that knows BEM full stack of technologies. Every other team would kill for such an asset! It was an additional layer of responsibility for us :)

We started to discuss tasks that I prepared beforehand and soon enough decided to start working on the structure of the site.

We had two basic goals:
1. Revise bem.info current structure and understand why it is uncomfortable;
1. Develop the basic principles for preparation of the information on the site and its publication, that it would help developers.

Faced the problem of inefficiency working all together on every other task. We understood that we started from the wrong side and had different points of view about the discussion subject.

![](https://img-fotki.yandex.ru/get/15483/44214498.bc/0_9bbea_9d1a1876_XL.jpg)

We overcame difficulties and went further on. Started to work on the new structure but everyone from his side (we split roles) – somebody analyzed materials on the other sites, somebody decided how to formalize text, somebody worked on the structure itself. We decided to take not only our own preferences, but to hear out the developers that use our documentation. This is how our survey was born.

First of all we questioned hackathon participants, than asked the community. We created a survey and asked everyone to fill it in. Many thanks to everyone who found 5 minutes and helped us with answers! Surprisingly the majority did it. Data continued to come during the whole hackathon, even at 3 a.m. and 8 a.m!

What we have found out:
* Current amount of documentation is enough for almost a half of developers (Yes – 41% / No – 59%);
* When they lack documentation, they lack step-by-step manuals on «setting and tuning in production», «using together with backend-frameworks», «setting building samples and tests», «on i-bem.js with all methods and samples», video lessons, «simple tutorials», «navigation guide on documentation»;
* Documentation on technologies, BEMHTML reference, documentation on libraries and quick start with project-stub helped working with BEM;
* The following content of bem.info is popular: «Technologies» – 24%, «Libraries» – 24%, «Forum (only Russian version is available in the meantime)» – 16%, «Tools» – 11%, «Talks» – 10%, «Articles» – 8%, «Methodology» – 6%;
* The majority of questioned think that BEM documentation is hard to understand – 74% vs. 26%;
* Developers choose big volumes of documentation if they structured well (36%) and workshops (26%). Some are willing to watch lessons (19%). Short documentation needed only by 17%;
* Almost all questioned agree that the site lacks interactive samples and manuals, video lessons and graphical support of the text;
* We were pleased to hear that "we did a great job on restructuring and complementing documentation, it is now MORE BETTER, thank you!».

The task delegation approach was efficient: before a dinner time we had ready-to-go brand a new structure of the site and basic rules for the content forming, that we want to follow in the future. Of course, it is a proposition that needs to be developed well and agreed with BEM team.

In terms of hackathon we had not so much time left to solve all the problems. We decided to translate documentation that everyone was waiting for. Misha Baranov started to translate! And we added his profile to the [author page](https://en.bem.info/authors/baranov-mikhail/), because all the translations were published under his name :) Thank you so much!

First hard hack-day went to an end. People started leaving after 10 p.m., but there were developers working up to 3 a.m. and even until morning comes.

Next day morning was sleepy. We met on coffeepoint, talked about projects. Time was running out and we needed to finish our work and prepare the presentation of the project.

But.. we decided to start working on the next document. The idea came right after the answers we got in our survey. Developers told us that our current BEM quick start is not that quick. We worked all together to get done as much as we could! Vika wrote a text, Misha coded, I put two days work in the final slides.

### Presentations of results

One after another teams presented results of two day hackathon and told us the future plans.

While presenting BEM Documentation team results, we showed the main idea of the new structure, described basic principles for preparation of the information on the site and its publication and discussed survey results. Misha showed new quick start idea in practice.

During two days we finished the following:
* Defined **bem.info future development directions** the idea of which is to divide methodological and platform parts and put every technology information into its own section.
* Developed **basic principles for the content**. This set of principles will be available on the site once the new structure is ready.
* **Got feedback** and **made conclusions**. For instance, we though that one of the main problem is too big and difficult-to-understand documents. However the problem is not there. Our survey showed us that developers are ready to read big volumes if they structured well and "seasoned" with useful examples.
* Started working on the new document called "Creating a static page according to BEM" that is going to be truly useful and quick start for newcomers. Document is in development status. We plan to publish it in the nearest future.
* **The following documentation was translated**:
 * [COA](http://en.bem.info/tools/bem/coa/)
 * [Static resources 'freeze'](http://en.bem.info/tools/optimizers/borschik/freeze/)
 * [Where is my tech](http://en.bem.info/tools/optimizers/borschik/where-is-my-tech/)
 * [JS include notations](http://en.bem.info/tools/optimizers/borschik/js-include/).

When everyone presented, we voted for the winners (yes, there was a competition!) and, or course, chose them! They got prizes (interesting books from [«Mann, Ivanov and Ferber»](http://www.mann-ivanov-ferber.ru/) printing house and T-shirt). And of course we did group and team photos. Than we had a dinner and a night Moscow walk.

## Resume and impressions

During the hackathon our team managed to finish not only the main tasks but did a little beyond. Two days were productive and filled with emotions!

After that I had a lot of new ideas on what to prepare before the new hackathon (I do not question if it would be, I am sure it would :) ), how to manage time well, what problems to examine before the hackathon and how to manage the team and the process.

Impressions and inspiration are more than enough for a long time! These two days were filled with team work and emotions, common goals, team spirit! I was pleased that the competition was healthy, common touch was supported by common help and advises: developers from different teams discussed their tasks and even (this is totally cool!) used what they created as early-adopters! This was soulful and awesome!

Thank you so much and **Stay BEMed**!

![](https://img-fotki.yandex.ru/get/17893/44214498.be/0_9bc3a_372492bd_XL.jpg)