side-project,  documentation,  planning

Planning and documenting a side project

Building an AI Audio Guide - Part 2

Planning and documenting a side project

This is the second part of a series of articles about prototyping an AI audio guide app. Missed the other parts? There you go: Part 1 and Part 3.

In the first part we talked about how to go from an idea to a basic prototype. Now, in this short article I’d like to give my 2 cents on how to document and plan the execution of that idea, or any side project.

Mind you that this is not a tutorial, but rather a case study of how I approached this topic. Besides, it’s important to say that this works best for very early stage projects, where you have a lot of questions and not many answers.

What’s next?

I was sure that the core functionality worked and I could start building an app around that idea. But at this point of the project there are a lot of open questions, like:

  • How would I structure the project and what architecture to use.
  • Which libraries would be needed?
  • How would the app flow would look like? What about the design? The UX?
  • What permissions do I need? When to ask them?
  • How could I improve the prompts? Is prompt engineering an actual thing?
  • How would I display the actual output to the user? Show a text? Just play the audio? How does the UI for an AI audio guide look like?

The more you think about the more questions you get.

Obsidian and Mind Maps

The first thing you need to do at this point is putting all those questions in a place where you can see them all at once. Then you start answering and organizing the answers into categories. This is where mind maps come in handy.

Notes help a lot, but you’ve probably been at this place where you write down a bunch of notes, but you can’t make sense of them. Or they don’t seem to connect, and you can’t see the big picture. To fix that we can use something like Obsidian.

It is already my go-to note-taking tool, but it’s also great for mind mapping with the canvas feature. Each note is a node, and you can link them. Notes can even reference each other with hyperlinks, so you can easily navigate between them. It’s all going there - diagrams, designs, ideas, case studies, laid out in a big mind map with all those markdown files. So, let’s get to it.

The two starting nodes were these:

From there you can start to break down the project into smaller parts and try to focus on each one at a time.

Research and documentation

Those starting nodes would prompt questions I had to answer, which lead to other topics I had to research and document. For example, I would research which APIs I could use, then document the steps to use each of them, think API request examples, dashboard panels, links, api keys, and so on. Then, when I was ready to integrate it to the project I had a clear path to follow.

For example, to answer the question “how to add location context to the LLM prompt” I had a simple idea: Use the device’s GPS to get exact coordinates, then use the Geocoding API to get the precise address, finally we could fetch the top 5 tourist attractions near those coordinates.

After some research I figured that the Places SDK could solve that, but after testing I realised it doesn’t filter for tourist attractions, so I had to resort to using the plain REST API.

Having done that, I could step back and take a look at the big picture. I could see the whole process of getting the data I needed to build the experience I wanted.

This process also worked when defining how I wanted the app flow to look like. Starting from sequence Diagrams, wireframe sketches, and finally a higher-fidelity design.

All this information linked in the same space, makes it easy to navigate and understand the project as a whole.

Here is the full mind map. I included information about decisions and documentation on prompt engineering, design, UX, sequence flows, even a Kanban board for tracking the feature backlog. Having worked on other side projects where I didn’t document anything, I can say that this approach is a game changer.

Wrapping up

This whole documentation topic might seem like a chore or just irrelevant, but especially when it comes to side projects, they can be crucial for taking an idea to fruition. But we usually just don’t pay enough attention to it, which often leads to wasted effort and sometimes giving up on an idea altogether (been there, done that). Besides this, there are the obvious benefits of having a clear plan and an organized place to find important information.

All of this is vital for keeping side projects alive. It’s easy to lose interest and move on when you hit roadblocks, so having a dedicated space to store your thought process makes it much easier to pick up where you left off.

In the next and final article, we’ll talk about a mental model for architecture decisions, trade-offs, learnings, and guidelines. See you there!

Jump to Part 3