1. Clearly, something has to be said about Instructables. As awesome as the site is (I've been a member since only a few months after it started), one thing that bothers me is the manner in which picking pictures for your projects is carried out. I think pictures are a really important part of documentation.

As I see it, you document a project for two reasons only: to learn from your mistakes and to reproduce your successes. You need to write and speak clearly, and explain what you have done or are doing fully. Think about how you figured out how to do this, and how you can help someone else do the same.

Pictures are really helpful in this regard, especially since writing about putting pieces together is almost impossible. These needn't be high quality poster shots, but they should be in focus. In fact, a smaller picture is often better as people really don't want to wait for a download. Thumbnails or preview images are key.

I have given many lectures to middle school students, and I find that thinking about explaining something to them can be the best way to explain it to anyone. You've probably seen some of my projects before, but if you're interested in seeing how I personally document check out my projects page:
http://mustardhamsters.com/?cat=4
Although it isn't finished yet, you may also want to keep up with my modular room control project. This is a two year long effort that is just now being polished, and many of my current projects are actually modules or pieces of this larger effort:
http://mustardhamsters.com/?page_id=194

Documentation is hard, but you need to do it not only to share your work with other people, but to see how to improve your current projects and see potential for new ones.

Posted at 7:48PM on Feb 22nd 2008 by Dean Putney

2. 1- Full description of the project objective.
2- Photos!
3- Schematics, sourcecode, and all of this well made.
4- More photos.

Posted at 7:49PM on Feb 22nd 2008 by Juan Cubillo

3. i find that LAYOUT is important. it peeves me to go to a writeup and the page is black with dark blue text and blury photos.

as much effort as the project should go into the writeup.

Posted at 8:33PM on Feb 22nd 2008 by johanthon

4. I think the most important thing is providing a complete, well-chosen parts list. I don't just mean list them all, but choose them knowing that some of the parts will be unavailable for one of a million reason (price, impatience, import/export law, etc). Instead, describe the reason or role of each part, so a motivated person can substitute as necessary.

Posted at 9:06PM on Feb 22nd 2008 by nickjohnson

5. I love the way LadyAda documents her projects, really sharp detailed pictures with flickr-like notes.

The phrase, "A picture is a thousand words" is very apt. It means I can have visual verification of what your saying, it also provides a quick check, if it doesn't look like what you have, then I may be doing some thing wrong.

Posted at 9:34PM on Feb 22nd 2008 by TheFallen

6. Where you got all of the parts for said project.

Posted at 10:51PM on Feb 22nd 2008 by epicelite

7. Well commented code!

Also, discussing the mistakes you made and how you went about fixing them, as well as alternative solutions.

Posted at 11:06PM on Feb 22nd 2008 by goldscott

8. I am all for full disclosure, sourcecode, schematics, everything; but it's really annoying when you have to download a zip file with all the files just to see one, and even more so if it's something like a gerber file. I shouldn't have to install a new program just to get an idea how the thing works. Reading documentation and reproducing a project are 2 different activities and the content makers need to keep that in mind when writing. All the documentation should be web accesible with out extra software or downloads.

Posted at 11:31PM on Feb 22nd 2008 by sumguy

9. I'm of the opinion that a how-to is nothing without good pictures. Get a nice diffuser and a professional flash setup, not to mention a nice 60mm macro lens. That'll set you back a lot of money, but your pictures will look nice, and that means that it's easier to follow instructions, not to mention that its more likely to draw in more people to the project (pretty pictures sell ideas well). As long as you can write, I think that's all you need.

Posted at 1:15AM on Feb 23rd 2008 by Michael Witt

10. Most of the important points are already taken but to take it a step further and talk about _WEB_ documentation specifically I think there are two very important aspects to consider

1. keep everything on a single page that can be viewed by a browser and indexed by a search engine. If you MUST break it up across multiple pages then ensure that the title, current step, and keywords associated with the project appear on all pages. It's also preferable that you host it somewhere it can stay for the forseeable future.

Attention college students: that uni provided hosting wont last past graduation, and neither will your project's legacy if you don't host it elsewhere.

3. All files should be in a platform independent format. If you've got an Eagle PCB schematic, great, zip that up for people, but also provide them with a .jpg, .gif, or .pdf so they can view it right in their browser. you have source code? great, throw that in a .txt outside of the zip as well so people can view that too. Everyone viewing your documentation via the web will have a web browser, so it's a good idea to ensure that all of your documentation can be viewed by a web browser... it's pretty simple really.

3. Google use the alt text in html image tags to label images for their search, be sure to put the project name and useful information about the project in there if you want those pictures to get indexed.

4. If you took some pics with your digital camera at it's full resolution and left them that size and with the generic naming... that can be great for detail but do us all a favor and instead of hyper linking to 100+ generically named images, size them down physically and dimensionally and display them on the page with links to the full size photo.

5. Not realy web specific, but good and more specifically consistant formatting is important. Some rules to follow for formatting

a. tell them what you're going to tell them, tell them, and then tell them what you told them. title the project appropriately like "how to build a dohicky" or "modify your widget for bluetooth", provide a brief description about the goals of the project, what topics the project will cover and what it wont cover. Tell them the kind of tools, materials, and prior knowledge they'll need to accomplish the task (if a tutorial), then go through all the steps, then wrap it up by explaining what it all means and what the results should be like.

b.keep the steps or sections to a manageable size, have the breakup of steps make sense, and keep them small enough that someone could read a section and retain all of it for 5-10 minutes while they try to do it without having to keep going back to the step. Don't make them so small however that you insult the intelligence if your reader.

c.use strong visual cues to break up the steps, with a consistent numbering and formatting scheme throughout. If someone needs to glance back at the page to read something they don't want to have to scan through buckets of text to find their place again (this comment is exempt because I don't have control over the formatting :p ).

d.understand the knowledge level of your reader and write to that, don't over explain the basics if you're writing about an expert topic, and don't make ANY assumptions about what a beginner should already know. Also use appropriate vocabulary for the intended audience and never use slang, an acronym, or an abbreviation without explaining it at least once in the documentation (preferable the first time you mention the term).

Thats all I can think of for now.

Posted at 2:15AM on Feb 23rd 2008 by twistedsymphony

11. Pictures are important, but i often miss a well drawn schematic with signals drawn from left to right, separated (grouped) power supply with decoupling capacitors and comments.

Posted at 11:25AM on Feb 23rd 2008 by mandark

12. I work in an electronics failure analysis lab for NASA, and one of the biggest things about analyzing a failed part is the documentation of it. I cannot stress enough how important it is to records to take pictures of every major condition a part is in. For us, it is not uncommon to take hundreds of different photos of a part, even if we don't use all of them in our final report. Pictures are useful for the "oh gee, a scratch, was that there before?" as well as the simple explanation of what the part looks like outside and on the inside. Since digital cameras makes imaging so easy, and we have memory cards that hold thousands upon thousands of pictures, there's no reason not to take a lot of pictures.

That being said, it's also important to fully explain the details of what you're making. For example, electrical schematics, physical shapes, etc.

Posted at 11:53AM on Feb 23rd 2008 by Satiagraha

13. Personally, I feel that good grammar and spelling are essential in a good writeup. If I see a project with terrible spelling and grammar, I usually get turned off and just look at the pictures, saying "Hmm, that's interesting," and then forget about it.

Also important are clear diagrams and pictures to make it easier for a non-technical reader to understand. Links to relevant information are also a plus.

Posted at 12:01PM on Feb 23rd 2008 by Skyler Orlando

14. Pictures are very important. Step by step pictures are even better. With a detailed explanation about what you are doing and a good picture of what is happening a person can follow the project easily.

Parts and documentation as to the reason for using that part is crucial so that people are able to take your work to the next level. After all that is what hacking is about taking something and making it better.

A through theory of operation would make it easier to find errors with the build when others are duplicating what you have done. I have learned more from the theory of operation than from the schematics but you need the schematics in order for the theory of operation to make sense.

All of this makes for good documentation of your success and allows you to better learn from your failures.

Posted at 11:11PM on Feb 23rd 2008 by Mike

15. Pictures taken in close-up using a macro setting... instead of having to squint to try to make out detail :)

Posted at 6:04AM on Feb 25th 2008 by LoopyMind

16. Agreed with some of the other replies, pictures are worth a lot, especially when people speak/write different languages. It's also nice to see standards stuck to when writing up maps and things that use symbols. Like a ground symbol is pretty universal, so might as well use it instead of your own little squiggle.

Posted at 3:21PM on Feb 25th 2008 by sinerasis

17. Major kudos to this site and contributors. Lots of top notch work and ideas.

I'd like to see for each project a proper introduction and description of the problem being solved. The intros are sometimes rather vague, and with all the effort in describing the how-tos I can't always appreciate why someone would even be bothering.

I get the impression at times that the authors just dive in assuming the readers are of the same community and are familiar with the context. With nearly 25 years in electronics engineering I don't need anyone to hold my hand; just please take a paragraph or two (links are fine) to provide background and explain why I should care what you're doing. Hackaday is good for this; the linked sites are sometimes much less so.

As I've learned time and again from my own mistakes, try to anticipate the redundant time consuming stuff for your readers. 5 minutes of my time is NOT worth more than many accumulated hours of my readers' time. Include clear photos and diagrams, simple explanations, complete parts list with suppliers and estimated costs, list of tools, required and suggested utilities.

As with any prose, try to emulate those authors (and hackers) who make docs that are not just precise and instructive but are fun. And, add links to similar solutions if available, especially if they're commercial solutions (to rub it in).

Posted at 5:25PM on Feb 25th 2008 by JDN

18. Inventgeek does a good consistant job at it.
I hate instructables.

Posted at 5:35PM on Feb 25th 2008 by jason gibbens

19. Informative Article... AWESOME.

Posted at 6:28AM on Feb 28th 2008 by Eliseo

20. A related thought: documenting a project well is a *lot* of hard work.

Each level of media you add (e.g. text, diagrams, photographs, video) increases dramatically the amount of time it takes to document.

Ideally, find some way to encourage yourself to document as you go, I've found having a "personal wiki"/online lab/project notebook has helped.

Any documentation is better than none.

This also means it's important to appreciate when someone has taken the time to document their project.

--Phil.

Posted at 12:42AM on Mar 1st 2008 by follower