I have a lot of makers around me: the Taipei Hackerspace, the VIA Maker Club, Maker Faire Taipei that just finished this year's event recently, and a lot more. They all inspire me to do more projects, and over the years I've ended up writing a lot of "maker notebooks": records of the project I've made. Whether it is posting to my personal blog, or sharing on Instructables, I've found that there are a few guidelines that make your project write-up much more useful and interesting. While this list might make common sense, it is good to consciously ticking them off when you are writing (not everything what one knows turns into action at the time).
Pick your audience
Figuring out who is the intended reader of your notes have a big effect your writing. The style, amount of context and details required, the length all change when you are writing for a different audience.
One of the easiest, and in my experience most effective choice is writing for your future self. Think about your project 6 months, 1 year down the line. If you'd want to repeat it, improve on it, or just merely explain it to someone else, what would you need to know? You know how many things you had to figure out along the way when you were making your project. What gave you difficulties now, would probably give you difficulties in the future - and also would give difficulties to others most likely.
Put in context
Putting the work in context helps understanding it a lot. What was your inspiration and motivation? What related projects you have seen before, and how does this compare? What was lacking before, and what's the aim this time? This sets up the rest of the write-up, and makes it more engaging. If you are writing for your future self, it might jog your memory in the future when trying to untangle the question that inevitably arises in time: "why have I done it this way?"
Take plenty of pictures and video
While making your project, take plenty of pictures of the different phases of work. The steps you take, the parts you need, the way you assemble things... It's better to have more pictures and select from them for the writeup, than finding out later that a complex step has no illustration at all. Some places where you can post your write-up also let you tag and annotate the pictures, that can helps a lot with the explanation.
Lots of makers I've met don't like to take pictures, or only like taking pictures of the finished project. A bit of extra work does worth it on the long run in my experience.
When the results can be demonstrated, a video shows the results much better than any description would be able to do. For example this video is to show the workings of one particular hardware:
There are situations when explanation requires graphics. Could annotate a photo, though quite often I find that the picture will become too crowded and hard to understand. In those cases making a quick diagram can make all the difference: clean, to the point explanation of just the essential things. Connection diagrams, schematics, work steps, all good candidates for diagrams. Whenever you find that you'd need a whole paragraph or more to explain something, try a diagram instead (or in addition). Often it helps for even simpler explanations as well.
Include the source code
If your project include software, including the source code is essential. Recreating software when it is not included is much bigger barrier than fixing a mechanical design where the instructions are unclear. The best is to use a source control software and host it somewhere, but depending on how much code it is, including it in your note can also work. Sharing the software will also give you the experience on how much information is required to recreate a particular project, and to not share sensitive information (like your API keys, usernames, passwords....). This latter is a really essential skill for everyone working with software!
Include outstanding questions
If there are unfinished parts to your projects, or nice-to-have features that you are thinking about working on in the future, include those in the writeup. What-ifs, potential improvements, future directions, questions that fascinate you but haven't tested yet all add to the context of the project. These notes can help you to pick up later where you left of, or someone else to build on top of your work. Gives you more credibility as well, as your project is much better thought out this way.
Bonus: share it
Share your notes publicly. It lets other people learn from you, you can build expertise and credibility, and start a conversation with others who are working on similar topics. I have had writeups that generated interest months down the line, and revived my work on that project. In the worst case nobody reads the notes (including yourself). In the best case it opens doors for you - and for others.
And the most important in the end: have fun making!
Ps: if you have a project you want to show us, letme know in the comments!