It's difficult to start a new software project
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:
-
.gitignoreis 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. -
CHANGELOG.mdtakes very little effort to start, but is difficult to apply to an existing project.- Keep a changelog 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.
Top comments (0)