The first thing I do for every project is set up a development blog. Hugo + a nice free theme + Gitlab Pages + Netlify CMS. Everything is contained in Gitlab and I can keep the Pages site private and only accessible by members of the repo. It is less of a daily log and more exploring "issues" - basically anything I took time to research and figure out. I'm very adamant about recording details like dates, version numbers, context, code snippets, commands, and URLs of resources used. It all comes down to asking myself, if I see this issue again in the future, what information do I need to easily solve it without opening 40 browser tabs?
At first it takes some effort to circle back and write the post after you solved the issue, but after a while I found myself writing the post concurrent with writing my code. The Netlify CMS isn't the most beautiful UI but being able to just write markdown in a browser window eliminates having to keep a git repo locally. Organizing with categories and tags makes referencing published posts easy and if you want to get fancy you can integrate Algolia for search.
Honestly, having a project dev blog has saved me so much time since I don't need to keep every detail in my head anymore. Being able to go back and read about why certain decisions were made or how I overcame complicated problems is absolutely invaluable. And of course having this rich documentation while on-boarding new team members or passing the project off to someone else makes everything easier. Setting up a dev blog is 100% worth the minimal effort it takes.
I've been doing this for years, and even though basically no one reads my blog, it's nice to have a place where I put "polished" thoughts about my projects.
I love this. I have a grouping of pages in Notion for tech notes. But I really like the idea of scoping it to a project. I like that you don't need a local repo. I'll have to experiment with this. Have you automated anything for it? And do you have any patterns you use (eg. organizing the information, etc). Thanks!
There's really not much to automate. The Gitlab CI/CD config file to build Hugo and publish to Pages is always the same so I just re-use it as boilerplate. Likewise the Netlify config is usually the same as well, so once you've learned that syntax and structure it's not much work to put in place. I always like to peruse the latest Hugo free themes before I start and I usually end up using a new theme for each site anyway. The only real patterns in terms of organization is making sure I categorize and tag each post in a detailed manner. Most issues are related to a certain piece of the project or tech used, so when you know for example that your issue is related to the database then you can look at all posts categorized or tagged in a similar way to see if you already addressed the issue. I do find the most helpful step I took was making sure the post had a nice meaningful title with the proper keywords - that helps keep you from reading multiple posts until you find the one you need. Hugo and Gitlab's CI/CD are really great but the open source Netlify CMS is the key to making this setup so easy and remote only.
I tried to do this for my last project but ended up spending too much time making the blog and didn't get around to properly starting the project! Maybe instead of rolling my own site from scratch I'll use Hugo.
