documentation

19 Articles

Well Documented Code Helps Revive Decades-Old Commodore Project

June 7, 2023 by 15 Comments

In the 1980s, [Mike] was working on his own RPG for the Commodore 64, inspired by dungeon crawlers of the era like Ultima IV and Telengard, both some of his favorites. The mechanics and gameplay were fairly revolutionary for the time, and [Mike] wanted to develop some of these ideas, especially the idea of line-of-sight, even further with his own game. But an illness, a stint in the military, and the rest of life since the 80s got in the way of finishing this project. This always nagged at him, so he finally dug out his decades-old project, dusted out his old Commodore and other antique equipment, and is hoping to finish it by 2024.

Luckily [Mike’s] younger self went to some extremes documenting the project, starting with a map he created which was inspired by Dungeons and Dragons. There are printed notes from a Commodore 64 printer, including all of the assembly instructions, augmented with his handwritten notes to explain how everything worked. He also has handwritten notes, including character set plans, disk sector use plans, menus, player commands, character stats, and equipment, all saved on paper. The early code was written using a machine language monitor since [Mike] didn’t know about the existence of assemblers at the time. Eventually, he discovered them and attempted to rebuild the code on a Commodore 128 and then an Amiga, but never got everything working together. There is some working code still on a floppy disk, but a lot of it doesn’t work together either.

While not quite finished yet, [Mike] has a well-thought-out plan for completing the build, involving aggregating all of the commented source code and doing quarterly sprints from here on out to attempt to get the project finished. We’re all excited to see how this project fares in the future. Beyond the huge scope of this pet project, we’d also suggest that this is an excellent example of thoroughly commenting one’s code to avoid having to solve mysteries or reinvent wheels when revisiting projects months (or decades) later. After all, self-documenting code doesn’t exist.

Continue reading “Well Documented Code Helps Revive Decades-Old Commodore Project” →

Motion Canvas Helps Get Your Point Across

June 5, 2023 by 1 Comment

Generating videos for projects can be difficult. Not only do you have to create the thing, but you film the process and cut it together in a story that a viewer can follow. Explaining complex topics to the viewer often involves a whiteboard of some sort, but as we all know, it’s not always a perfect solution. [Jacob] was working on a video game and making videos to document the progress and built a tool called Motion Canvas to help visualize topics like custom shaders. A few months ago, he decided to release it as an open source project.

Since then, it has seen quite a few forks and GitHub forks with a lively showcase on the community Discord. Looking at the docs, it is pretty easy to see why. The interface allows you to write procedural animations using the async semantics of TypeScript while still offering the GUI interface we expect from our video editors. In particular, the signal system allows dependencies to be defined between values. The system runs in Node, and the GUI runs in your browser locally while you edit the files in your terminal/notepad/IDE. CSS and Flexbox are available as the video is rendered to a web canvas and then compiled into a video via FFMPEG. The documentation is quite extensive, and it’s a great example of a tool someone built to fit a need they had going on to become something a little more fantastic.

This isn’t the first time we’ve discussed how to share your projects with the world, and we’ll freely admit we have a bit of bias toward encouraging folks to document their projects.

Continue reading “Motion Canvas Helps Get Your Point Across” →

Automatic Microfiche Scanner Digitizes Docs

September 17, 2021 by 18 Comments

While the concept might seem quaint to us today, microfiche was once a very compelling way to store and distribute documents. By optically shrinking them down to just a few percent of their original size, hundreds of pages could be stored on a piece of high-resolution film. A box of said films could store the equivalent of several gigabytes of text and images, and reading them back only required a relatively simple projection machine.

As [Joerg Hoppe] explains in the write-up for his automatic microfiche scanner, companies such as Digital Equipment Corporation (DEC) made extensive use of this technology to distribute manuals, schematics, and even source code to their service departments in the 70s and 80s. Luckily, that means hard copies of all this valuable information still exist in excellent condition decades after DEC published it. The downside, of course, is that microfiche viewers aren’t exactly something you can pick up at the local Big Box electronics store these days. To make this information accessible to current and future generations, it needs to be digitized.

The camera panning over a full DEC microfiche sheet.

[Joerg] notes there are commercial services that would do this for you, but the prices are just too high to be practical for the hobbyist. The same for turn-key microfiche scanners. Which is why he’s developed this hardware and software system specifically to digitize DEC documents. The user enters in the information written on the top of the microfiche into the software, and then places it onto the machine itself which is based on a cheap 3D printer.

The device moves a Canon DSLR camera and appropriate magnifying optics in two dimensions over the film, using the Z axis to fine-tune the focus, and then commands the camera to take an image of each page. These are then passed through various filters to clean up the image, and compiled into PDFs that can be easily viewed on modern hardware. The digital documents can be further run though optical character recognition (OCR) so the text can be easily searched and manipulated. In the video after the break you can see that the whole process is rather involved, but once the settled into the workflow, [Joerg] says his scanner can digitize 100 pages in around 10 minutes.

A machine like this is invaluable if you’ve got a trove of microfiche documents to get through, but if you’ve just got a sheet or two you’d like to take a peek at, [CuriousMarc] put together a simple rig using a digital microscope and a salvaged light box that should work in a pinch.

Continue reading “Automatic Microfiche Scanner Digitizes Docs” →

Tool Generates Interactive PCB Diagrams From KiCAD

August 3, 2021 by 21 Comments

Nearly everyone likes nice pinout diagrams, but the more pins and functions are involved, the more cluttered and less useful the diagram becomes. To address this, [Jan Mrázek] created Pinion, a tool to help generate interactive diagrams from KiCad design files.

The result is an interactive diagram that can be viewed in any web browser. Hovering over a pin or pad highlights those signals with a callout for the name, and clicking makes it stay highlighted for easier reference. Further information can be as detailed or as brief as needed.

Interestingly, Pinion isn’t a web service that relies on any kind of backend. The diagrams are static HTML and JavaScript only, easily included in web pages or embedded in GitHub documentation.

If you think Pinion looks a bit familiar, you’re probably remembering that we covered [Jan]’s much earlier PcbDraw tool, which turned KiCad board files into SVG renderings but had no ability to add labels or interactivity. Pinion is an evolution of that earlier idea, and its diagrams are able to act as both documentation and interactive reference, with no reliance on any kind of external service.

Interested? Pinion has a full tutorial and demo and a growing library of parts, so check it out.

An Open Source Tool To Document Your Wiring

June 23, 2020 by 29 Comments

Most of us are familiar with the tools available to create circuit diagrams, as generally that’s the first step towards producing a custom PCB. But that about the cables and wiring harnesses that don’t live on your board? How do you easily document the rat’s nest perfectly logical wiring of your latest and greatest creation?

That’s precisely the question that led [Daniel Rojas] to create WireViz. This open source Python tool takes human readable input files and turns them into attractive and functional visualizations of where all the wires in your project are going. It can even be used to generate a Bill of Materials that documents the lengths of wire required and types of connectors needed to hook everything up.

If you’re still using pre-made cables to connect all of your components together, than you might not immediately see the benefit of a tool like this. But as we’ve talked about in the past, the creation of custom wiring harnesses is something that serious hardware hackers should become familiar with. Yes it takes more effort, but the end result is worth it. With a tool like WireViz, the creation of a bespoke harness for your next project just got a little bit easier.

[Daniel] has done a fantastic job documenting this project, providing not only a tutorial on how to feed and care for your WireViz, but a gallery of examples that shows off the kind of complex wiring the tool can help make sense of. But there’s plenty more to be done, and he’s happy to get feedback or code contributions from anyone who wants to get involved.

Beautiful Sourdough Bread At Home Thanks To Dynamic Recipe Parameterization

May 26, 2020 by 21 Comments

More people are making sourdough at home than ever before, and while it may not take a lot of effort to find a decent recipe, it’s quite another thing to try using recipes to figure out how and why bread actually works. Thankfully, [Makefast Workshop] has turned copious research and hundreds of trials into a dynamic sourdough (and semi-sourdough) bread recipe chock-full of of drop-down options to customize not just ingredients, but baking methods and other recipe elements as well. Want to adjust quantities or loaf styles? Play with hydration or flour type? It’s all right there, and they even have quick-set options for their personal favorites.

In order to do all this, [Makefast Workshop] needed to understand bread at a deeper level than is usually called for. During research, they observed that the format of recipes was often an obstacle to understanding how good bread actually gets made. The reason for this is simple: recipes are presented as standalone documents describing a fixed process; a set of specific steps that, when followed, yield a particular result. What they do not normally do is describe the interplay and balance between ingredients and processes, which makes it difficult to understand how and why exactly the recipe produces what it does. Without that knowledge, it’s impossible to know what elements can be adjusted, and how. The dynamic recipe changes all that.

[Makefast Workshop] performed hundreds of tests, dialing in parameters one by one, to gain the insights needed to populate their dynamic recipe. It’s got clear processes and drop-down options that dynamically update not just the recipe steps, but also the URL. This means that one can fiddle the recipe to one’s desire, then simply copy and paste the URL to keep track of what one has baked.

When it comes to thoughtful approaches to food, this certainly isn’t [Makefast Workshop]’s first rodeo. We covered their beautiful directions for creating delicious speculoos, complete with effective 3D printed molds for a modern twist on a Belgian classic.

It Ain’t Over ‘Til The Paperwork Is Done: Test Driving TiddlyWiki

February 14, 2020 by 25 Comments

Working on projects is fun. Documenting them is often not so much. However, if you want anyone to duplicate your work — or even just want to remember what you were doing a few years ago when something needs upgrading or repairing.

There’s a ton of ways to keep track of the details of your projects. We love seeing how things come together and of course we’re happy to suggest documenting on Hackaday.io. But sometimes, you just want to keep your own notes to yourself. There’s always a notebook, of course, but that seems kind of old fashioned. A lot of projects are on Wikis but you hate to stand up a web server and a Wiki instance just to keep notes. But what if you could have a local Wiki with minimal setup?

I recently came across TiddlyWiki and decided to take it for a spin. Join me after to break to see what it’s all about.

Continue reading “It Ain’t Over ‘Til The Paperwork Is Done: Test Driving TiddlyWiki” →