Upcoming Events/Appearances

UI Components Doc Sprint: Hello Kyiv!

“There are a handful of people in the world who truly understand UI Components well, and putting them in a room together for a full week made for a fascinating event.”

Magento 2, like all feature-rich platforms, has some complexities. UI Components, introduced in 2.0, is a feature with perhaps one of the biggest needs for solid documentation.

The power of being able to quickly add a button set, drop-down list, or a new form onto a page, and then to be able to customize that element as deeply as needed, is easily understood.

But the nuances of the code structure, the configuration workflow, and the many parts and pieces of a UI Component instance require a closer look to really understand. Data sources, .php modifiers, generated JSON content, a lot of xml, nested nodes that allow for an extreme level of customization, Javascript, .xhtml templates… there is a lot going on. And when things don’t work, what about debugging??

The community asked for better documentation around UI Components, and we heard you. We would like to thank some very specific wording in one particularly painful GitHub Issue; a few key phrases resulted in the first ever Magento Doc Sprint. Thank You and Дякую!

Hello Kyiv

About two thirds of our development and testing teams are in the beautiful city of Kyiv (along with many other essential staff). The office there is spread out on two floors of a big, modern building (with an amazing coffee shop on the ground floor). I’ve been to Kyiv four times over the past 9 years for software dev work, and I can say that the energy level and creativity buzz in the Magento offices is incredible and unmatched. I could barely wait to get started!

The engineers who developed UI Components, with guidance from our resident yogi Vitaliy Korotun, are there. The Frontend team is one of the many dedicated scrum teams in the Kyiv offices, and they were the ones I needed to talk to.

DevDocs realized that we need get the deep technical knowledge that is in their heads out and into the documentation, and a Doc Sprint is a terrifically effective method for doing this.

But Magento had never done one before, most developers in the world haven’t (*yet*!), so there had to be some warm-up conversations, some explanations, and well… convincing.

Brief History of Doc Sprints

Doc Sprints have been around for a while; small, company-specific ones started in the late 2000s. In 2011 gnome hosted a popular event in exotic Brno, Czech Republic, and Mozilla sponsored a Javascript-centric Doc Sprint in Berlin. Australia-based Atlassian made an art form of them in the early 2010s, with across-the-globe, simultaneous, live-feed Doc Sprints fueled by chocolate.

The word “sprint” was, from the beginning, applied in the exact spirit of the word: it’s a race, it’s intensive, and it’s short. When Doc Sprints started, though, Agile and our current understanding of sprints was just being formalized. Now in 2016, typical scrum sprints involve code, testing, and documenting… and the two-week sprints used at Magento are the work-horse method for consistently adding new functionality to the product… but it takes many many two-week sprints to get a good amount of docs created.

A Doc sprint, focused 100% on documentation, is much faster… and since the docs are written by the developer who actually created the functionality, the technical depth and insight goes directly out of the developer’s brain and straight into the documentation.

And they’re fun… similar to Hackathons, a Doc Sprint (also called a Doc-a-thon) eschews any overly formal processes, and emphasizes the act of identifying required documentation and then very quickly producing it. Doc Sprints can be an intense, laughter-filled, brain-draining, and multi-cultural collaborative act of creation, resulting in a quality of docs that most easily come straight from the core developers who created the code.

How it works

Before we get into the logistics, let’s cover some important new glossary terms:

Extreme Editing: [verb, from the practice of extreme programming] the process of 3-6 people "demo'ing" on the big screen the previous session's documentation topics, and everyone together editing and tweaking the words and code samples. This was my favorite part of the Doc Sprint; the bursts of impassioned, intense conversations in Russian and Ukrainian... and then the final, "OK, this is how it works..." in English, for my benefit. ;-)

Developer-Who-Writes: [noun] The instantiation of a coder who really knows his or her stuff, and wants to take pride and ownership in sharing their deep knowledge. Not that rare of a creature, after all.

Our Doc Sprint Days

A team of developers, an architect, a product owner, and two tech writers walked into a room… and hashed out a rough outline for a new UI Components Guide. Our work started with carefully analyzing the many, many community questions and complaints; what were our users asking for? Sasha, the technical writer for Frontend work, created a wiki page with a rather large table of community issues, with a column for distilling the exact pain points of each GitHub Issue, StackExchange post, Tweet, and email. What are the most contentious areas? What was most painful? We then discussed the traditional aspects of good documentation: Use cases, Examples, How Tos, Conceptual topics, navigation, etc.

By Monday afternoon, August 15th, we had a solid outline for the new guide. We invited additional team members to join for a final review of the proposed outline. Then on Monday evening we asked Vinai Kopp and Ryan Fowler to take a look and send comments, especially about the prioritization of the topics. (Thank you two!). Both internally and externally there was agreement that conceptural topics were badly needed: what are these things, why should I bother to learn them, advantages, caveats for when maybe you actually don’t want to use them, etc.

Ambitious outline… and these are just the conceptual topics!

Every day for the rest of the week had this basic structure:

1) morning demos of new articles, 2) extreme editing of the articles by whole team, 3) push to internal GitHub, 4) refine outline if needed, 5) pick next article to write, 6) go to a quiet area and write or stay in big room with pastries and write, 7) afternoon demo, 8) more extreme editing until we are all about to cry from brain and language exhaustion, 9) push to GitHub. Repeat for four days.

What a fun (and terrifying) challenge to convince a team of developers to take on a Doc Sprint (and write in a foreign language!), plus explain the spirit and concept and urgency, while keeping it fun with pastries, fruits, coffee and collaborative brainstorming. But it went really well.

It’s a true privilege to ask the basic prodding questions of say, How does one do troubleshooting or diagnostics around UI Components… and watch the developers think… and then they start brainstorming with themselves, out loud, then other developers jump in and start adding information or correcting or questioning or challenging, and next thing you know I can’t type fast enough.

Photos of Participants and our Workspaces

So many people helped in so many different ways. There has been tremendous support, all the way from early acceptance of the proposal, then throughout the actual week-long Sprint, and even now as the project continues at a reduced scale. In particular, the developers who sat in the room day after day, and took very seriously the challenge to explain UI Components, are forever my heroes.

I think that my biggest take-away from this Doc sprint (in addition to a start on some solid documentation) is that cross-team collaboration on almost anything is incredibly valuable. A product is simply better when it’s designed and built and tested and doc’ed by people who can learn other perspectives and create solutions together.

There were many “bonus” side-effects of this Doc Sprint, beyond getting the documents written:

Stronger consensus within core team about the feature and its implementation (Best Practices, etc.)

Enhanced sense of ownership, pride, and customer-focus in all participants

The participating technical writers now feel much better trained about UI Components

Product owners had a chance to assess community feedback in detail and consider some “opportunities”

And, I was really happy to learn that our core developers are excited to share with the community and to help with the understanding and adoption of Magento 2. This week-long event is hopefully yet another channel by which our core team can develop not only a better understanding of what our users want and need, but also a sense of ownership and joy in their code. Oh, and… a much deeper appreciation of the difficulty of using words to describe code implementation. 😉

Results, and What’s Next?

And the verdict is…. great, but we want more. We ended up with 6 topics, for five days work, about 5 hours each day, from 2.5 people (don’t ask). We focused on the Conceptual topics first, but next up are How Tos and also Debugging topics.

1. Publish what we have, and ask for feedback:

But for the next day or so, we are doing some final edits on the work from Kyiv. However, we want to hurry and get them out there, as raw as they are, so that our community can benefit from any new information AND can provide feedback and even contributions. We are including templates in the GitHub repo; please, if you know a lot about a particular topic, grab a template and send us a PR with your content. Remember, DevDocs will add your name beneath each topic you contribute and we publish!

We will also publish the full outline as a simple .md file; we welcome feedback on the proposed topics and the organization.

Visit devdocs.magento.com to view the new UI Components Guide in its infancy, and all of the other DevDocs documentation.

NOTE: The original UI Components docs will reman for a while, but it will eventually be subsumed by the new Guide; saving, of course, all valuable content first.

2. Write More:

So we still have a lot to do. The project continues on a reduced schedule of 1-2 hours each day, with demos and extreme editing for each new topics on the Very Long outline. We have the interest and the commitment from the small team of core developers to “keep going forward”: Тiльки вперед!

3. Publish Again, and ask for more feedback

We plan to iteratively publish each week’s work in GitHub, and continue to add value and knowledge to our documentation about UI Components.

In Summary:

Let us know your thoughts: you know where we are on GitHub and on Twitter at @MagentoDevDocs, and please use Comments below as well.

And most importantly, Thank you and Дякую to our Magento core developers, the writers who participated, and to our community developers. Please keep the feedback coming: the good, the bad, and the ugly. An especially big thanks to Vinai and Ryan, who planted the seed for the first Magento Doc Sprint, and for their valuable review of our proposal early in the Doc Sprint.

Thanks Erik. It was a great week; wish I had taken more photos, and a video if it could have captured the wonderful dynamics in the room. Still a ton of work to do, but first steps in the right direction; efficient knowledge transfer! 😉