April 26th - 27th, 2014

"Project-level documentation is for managers, blocks-level documentation is for developers" by Vladimir Grinenko

Abstract: As you know, none loves to document code. However, it's needed to be done, because undocumented projects are very hard to maintain. Especially if you have many them. Its easier to get it over with once, and benefit from this further on. But... will it stay so forever? Of course, not. You need to update it, because there is nothing worse than a code which documentation is outdated and controversing about how it works. How do you deal with such a problem in your everyday routine? Probably well, if you use JSDoc format or similar for other technologies. It helps when your documentation is just about each property or method. But what do you do with more abstract documentation covering the whole project? Here in Yandex (http://company.yandex.com/) we created BEM (http://bem.info), a methodology for frontend development. It helped us a lot in developing and maintaining large scale projects with a tens bln audience and distributed teams working in more than 7 countries now on them. 4 years ago we open-sourced it, and not only the methodology, but building and optimizing tools, block libraries, template engine, etc. all working with one context in one terms, "speaking one language" so to say. You can check it out at http://bem.info or on http://github.com/bem. In BEM we have this idea of developing your product out of completely independent blocks (you may have WebComponents in mind, the idea is similar) where you have all the technologies you need (CSS, JS, templates, etc) inside it. And guess what? According to BEM, we put documentation as well as other technologies inside the block it belongs to. Our opensourced building tools provide possibility to build flexible site with documentation for each block. And as soon as the whole stack we have is based on JS, we developed our own JSDoc parser for node.js: https://github.com/bem/jsd. And we would be happy to share it talking at your conference. Speaker's bio: I am a web developer with more than 10 years of fronted experience from Ukraine. I have a lot of expertise in HTML5, CSS3 and JavaScript. Currently work for Yandex, Russian Search engine, leading a team that develops BEM (Block, Element, Modifier). I also evangelize a lot both in Russian and English and give live coding sessions as well as maintain and contribut to few open-source projects. I am free to talk about experience in BEM technologies (read more at bem.info), large scale web sites architecture, modular frontend applications development, etc. Outside of Yandex, I did a lot of studio web development. You can check my developer's profile at https://github.com/tadatuta/

This contribution is by Vladimir Grinenko

11 Votes

This is a response to the request Documentation Generators Best Practices from Matthias Seemann