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.

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).

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.

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

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.

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