As the developer of Mito [1], I rely heavily on Plotly [2] and pandas [3] documentation. They both have great documentation, IMO, because they have tons of examples with copy and pasteable code. Examples are great because:
1. they're easily parsable as the reader of the docs
2. they don't just tell me what to do, but they actually give me a starting place<p>I want to create docs for Mito that is as helpful as Plotly & Panda's docs. However, Mito is a spreadsheet, which means examples (screenshots) don't have the same characteristics as code examples:
1. they take up a lot of space on the page, making it difficult to scan through a page of docs for one that is relevant to the user's present problem.
2. you can't use the screenshot as a starting place, like you can with code examples. Instead, you need to replicate the screenshot in your own spreadsheet by following the same steps detailed in the screenshot.<p>Both 1 and 2 come together to additionally mean that what you can convey in a code example takes several screenshots to explain, especially when the user needs to pass through a sequence of clicks. For example, to create a graph in Mito, you need to first click on the graph button in the Mito toolbar, then click some more buttons in the taskpane that opens up. This makes using the documentation pretty frictiony.<p>In addition, screenshots are hard to maintain as we're constantly evolving our UI.<p>What are best practices for documenting a UI? What products do it best?<p>[1] https://www.trymito.io/
[2] https://plotly.com/python/bar-charts/
[3] https://pandas.pydata.org/docs/reference/api/pandas.pivot_table.html
I follow <a href="https://documentation.divio.com/" rel="nofollow">https://documentation.divio.com/</a><p>> There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four.
>
> They are: tutorials, how-to guides, technical reference and explanation. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most documentation - often immensely.