Automating style guide documentation

Automating style guide documentation

FOSDEM 2018

An automated approach for documenting a styleguide and the source code

Introduction

This talk is about how, we at Zalando Retail Core, are tackling the problem of providing our developers a great experience when they are using our styleguide. The talk will show that in using Markdown as the documentation format, a couple of convention, documentation.js for generating Markdown from jsdocs comments and our own Styleguide web application, we were able speed up our styleguide and source code documentation and the developer experience. Additionally, without relying on any static generator project with their own convention we are now able to fully control and change the user experience of our styleguide and are owning the whole documentation tool chain.

An automated approach for documenting a styleguide and the source code

Introduction

This talk is about how, we at Zalando Retail Core, are tackling the problem of providing our developers a great experience when they are using our styleguide. The talk will show that in using Markdown as the documentation format, a couple of convention, documentation.js for generating Markdown from jsdocs comments and our own Styleguide web application, we were able speed up our styleguide and source code documentation and the developer experience. Additionally, without relying on any static generator project with their own convention we are now able to fully control and change the user experience of our styleguide and are owning the whole documentation tool chain.

Details

As part of the talk , I want to show attendees:

• The benefit of using Markdown as a shared data object for documenting
• tightly Coupling documentation of our to the repository and the domain instead of separating it into different projects. Documentation for React components is part of their JSDocs, a dedicated docs/ folder for creating high level description (How to use it the component vs. it's internal methods and API).
• How relying on Markdown helped us reduce the maintenance cost as we were able to involve also our UX designers -> shared ownership thanks
• How having full control on behaviour of the styleguide web application helped us to develop our own design and implement it as a normal web application rather then providing templates an understanding API's of existing static site generators.
• We take our documentation serious and therefore any PR needs to update the documentation (if necessary) -> PR templates are really helpful here.
• Using a CI solution helped us also to automatically build generate and test our markdown files, check if our styleguide application is working with these new applications (regression testing of our app)

The talk will be about our decision process and our current workflow in generating up-to-date documentation as part of the development process.

Speakers: Ferit Topcu