How to write Installation Documentation
MagicMirror is meant to be accessible to all anyone with at any skill level. But to help promote building technical skills and educate in these technologies, require a little bit of 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 surely make sure to relieve your github issues from excessive novice questions and in addition make 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 doc 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 depend 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 SW in github are under some development.
Are your screenshots up-to-date with how the UI actually look?
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 need more attention. (Perhaps the UI, a dependency or link has changed?)
- Or are you going to be a cocky ass and give degrading comments?