Organizing Foundations Content

[kmpaul]

@andersy005 recently pointed me to this:

https://divio-documentation-system.readthedocs-hosted.com/

Ignore what Divio is as a company, and just focus on the fact that they wrote up a system on how to write good documentation. Yes, I think they wrote this specifically to help people learn how to write good software documentation, but I think it is generally useful for what we are trying to do in Project Pythia (...and, yes, we are also trying to teach people how to use software).

It's worth a read, but for the TL;DR crowd, here's the summary: good documentation needs 4 components:

• tutorials, which are geared toward teaching newcomers how to get started with the technology,
• how-to guides, which are geared toward showing how to solve specific problems with the technology,
• reference, which is geared toward describing the machinery of the technology and what each part does, and
• explanations/background, which is geared toward providing background material and explanations that give broader understanding as to why the technology exists, why it is designed the way it is designed, and complex concepts addressed by the technology.

And one more important things is that each component should be separated from the other components (i.e., each one in its own section).

I am wondering if thinking about this kind of organization for our educational content can help us:

• identify specifically what kinds of content we are missing and for which topics, and
• structure our content in a way that makes finding exactly what a visitor to our pages easier and faster.

Something to think about and discuss.