Circumventing Coder's block and starting a new project
Published: 2023-08-26 17:39:21

---
title: Circumventing Coder's block and starting a new project
published: true
date: 2023-08-26 09:00:00 UTC
tags: 
canonical_url: https://blog.engyak.co/2023/08/writers-block/
---

## It's difficult to start a new software project

![Road Block](https://blog.engyak.co/2023/08/writers-block/share.png)

### Documentation

Depending on how a software project starts, it can either be the easiest or the hardest aspect of a new project.

Documentation suffers from a similar issue, so a good place to get things moving would be to simplify the basics of repository management. Here's a number of things that _should_ be in a Git repository:

```
1.gitignore
2CHANGELOG.md
3README.md

```

Each of these things can be simplified in some way, and will make your future life easier. Let's start with the easy stuff:

- `.gitignore` is easily templated by your source control provider. At this point, it's smart to include one of their templates, this feature has really grown over the years.
  - [GitHub](https://github.com/github/gitignore) provides templates for common development setups, and integrates it into their new repository wizard.
  - [GitLab](https://docs.gitlab.com/ee/api/templates/gitignores.html) does too.
- `CHANGELOG.md` takes very little effort to start, but is difficult to apply to an existing project.
  - [Keep a changelog](https://keepachangelog.com/en/1.1.0/) provides an excellent template and guidance on how to effectively write changelogs.

`README.md` is the core of your project's documentation, and deserves separate mention because it's a powerful tool to organize how a project should function. Spend plenty of time on this part!

Since `README.md` is the page that renders by default in SCM, the objective _should_ be to provide everything a user needs to consume your software. I personally prefer to outline how the software should function and use it as a reference when writing the actual code. Here's a decent starting point:

```
 1# {{ Name the Project }}
 2
 3## Goal(s)
 4
 5{{ Write what your project should do }}
 6
 7## Overview
 8
 9### Validation
10
11{{ Write how functional software should be evaluated at an end-to-end level }}
12
13### Unit Testing
14
15{{ Write how functional software should be evaluated at a component level }}
16
17## HOWTO
18
19{{ Indicate how the software should be used. Provide examples, fix it later when the functional code revises your intricate plans }}
20
21## Software Dependencies
22
23{{ Include what the software will need to run. Update as you `include` new libraries}}
24
25## Contributors
26
27{{ Set up a place for software contributors to put their names. It might encourage participation }}

```

### CI

Continuous Integration is not easy to establish, but pays off over time as it catches small issues that appear throughout development. Since the testing strategy is written in plain language, CI tool setup is ideally started soon after the documentation. For a given CI tool, e.g. GitHub Actions or Jenkins, common practices can be templated for re-use.

### ...Then start writing code

From here, it's going to be _easier_ to begin authoring software from an outline. Start by writing out your plan ("pseudo-code") in comments, defining class structures if applicable.

Infrastructure automation is typically a play-by-play implementation of an operating procedure, which won't necessarily need object-oriented coding. In this case, the same approach still works - transpose the operating procedure as comments, and implement it as code.

### Hindsight

After some practice, it quickly becomes easier to start a new software repository. Structuring a software project quickly becomes important after only a few hundred lines of code - so if you're stuck, put some work in on the structure, it'll get the process moving, and the effort spent multiplies itself as the project grows.

Most Git providers also support _repoository templates_ - use this feature to create a form of "starter kit", and copy it whenever a new project is created to safe time.