Structuring user documentation and next steps

[maledr5]

I would like to open a live discussion about how our consumer documentation processes are shaped and evolve.

This Github discussion is meant to capture any ideas and challenges we discover regarding this topic and have one place to follow up how it evolves.

This are some of the open discussions and ongoing work regarding this topic:

1. Component Documentation

Engineering documentation:

We document some component information like props and event in each readme. The readme structure is part of our component generator and would be created from a template.
Some issues found with having docs in readmes are:

• We have to duplicate this content on pie docs, therefore we would have to figure out ways to automate copying the information
• When we need to do general changes, we have to update all readme files, which is cumbersome and not scalable

Proposed solutions

• ✅ Find out how other Design Systems are handling their engineer documentation
• Keep the README files simple and linking to pie docs, where we keep all component documentation only, as proposed in our definition of engineering docs for consumers (internal confluence link)
• Keep all contribution documentation on Github Wiki
• Find out a way to have Markdown Includes so when content needs to be repeated in every component docs, it has one main file where can be change only once (part of automation exploration)

Pie Docs

We are on the process of creating component content templates for PIE docs, this tickets should be ready and refined soon. Once this work is done we can work on adding the documentation for the components we already have developed as web components including: Button, Modal, Divider, Icon Button, Switch and Card

• Once this documentation is live, we need to include in our component development process the release of documentation as part of the Definition of Done of each new component.

2. Automation

We would like to explore automating some of this work so that updating information is not cumbersome or prone to fall out of date. Some ideas for future exploration and implementation are:

• Figure out ways to automate generation of docs that depend on code decisions, like props, events and tokens
• Find out a way to have Markdown Includes

3. Less technical content changes

We are exploring ways to enable everybody in the team to be able to contribute changes to our documentation content. Ideally at some point we can have some CMS solution but there are ways to make this possible sooner.

• Making and commiting changes directly from github by changing content from markdown files
  • Create documentation in confluence on how this can be done
  • Engineers pairing with anybody interested in learning how to make changes in content by updating markdown files
• Explore open source headless CMS solutions that can be integrated to our current content structure like Tina or Strapi

4. Understand how to integrate mobile documentation

At the moment we are figuring out how documentation for mobile is handled in other Design Systems. We would like to see what can we include in Pie, and if there are ways we can automate some tasks to generate docs (example for ios)

Feel free to add any comments, missing action items or ideas.