# How to write good documentation

MagicMirror is meant to be accessible to anyone with any skill level. But to help promote building technical skills and educate in these technologies, it requires a little more effort from developers to make their amazing projects more easily obtainable by ordinary people.

Most novices coming to MM are overwhelmed by the amount of information and perhaps even the technology itself. To overcome this obstacle, they need a lot of help in getting things going. As with anything we learn in life, we take it one step at the time.

Here is a guideline for writing a non-technical installation documentation to help people use your creation.

It's in no way meant to be exhaustive, but it will try to make sure to relieve your github issues from excessive novice questions and in addition makes it much easier to post good and useful answers.

# The most important points in writing software installation documentation:

  • Don't assume any previous knowledge! This is by far, the number one documentation issue and failure!
  • Does the software depend on any other, previously installed software?
    • If so make sure to either re-iterate the steps or link to equivalently good installation instructions.
    • Specify exactly what it depends on, and where to find it.
  • Are the steps following a logical order of operations?
    You'll be surprised!
  • Is the information you give correct?
    Don't guess how things work!
  • Are all the steps up-to-date with current master repository code and functionality?
    This is the hardest to keep up, since most projects in github are constantly under development.
  • Are your screenshots up-to-date with how the UI actually looks?
    You have screenshots, right!? A million of your words could never replace them.
  • Have you started from scratch and followed your own installation instructions?
    This step is what fails 99.9% of all documentation. Unfortunately developers are incredibly lazy in this regard, since they think it's a waste of time. I'm sure NASA has something to teach you about this.
  • Can anyone complete the steps successfully?
    Can your 9 year old baby sister or grandma follow the steps without asking for help?
  • Can anyone raise a question in the github issues?
    • Are you going to answer respectfully, short and concise and point the user to where to find the information, and take into consideration that perhaps something is not clear from your documentation and needs more attention. (Perhaps the UI, a dependency or link has changed?)
    • Or are you going to be a cocky ass and give degrading comments?

# And always remember: IF YOU WRITE IT GOOD, THEY WILL COME!