How do I structure my programming projects
I wanted to title this as "How to structure projects", but enough people have done that mistake of presenting their fresh thoughts as a best practice.
I avoid deciding the structure myself because the software usually shows what kind of structure it will form, that is always different than what I would have chosen for it.
I write for an audience
The software shows the shape it takes, but it doesn't usually name the structure. I think the trick to getting this right is to write it as if somebody would read it afterwards and he would have to make sense of it.
At outright this doesn't really help because writing for an audience can be harder than just programming. But it is a well-known subject people have studied hard for centuries and written about it.
I always use GIT
Even if I didn't publish anything, I always use revision control at every programming project I have. The logging provided by version control can get valuable later on, and the effort to set up GIT and maintain it is negligible.
README is for two purposes
The README in the project directory is usually the first thing that people see. It can also be the first thing you see when you resume to the project.
This means that README has two uses that are rather natural for it. It will communicate for the user if she happens to stumble upon the source code in the repository. It can also help to organize the workflow on the project.
From here you can derive that your usual project README would tell where to find documentation, how to build the project, what does the project's directory contain, the TODO list.
I've found out it to be rare to fetch a TODO list from among the source code. These days I directly write it to the README instead.
The documentation goes with the source code
I have learned to keep the documentation near the source code. The code itself is sprinkled with comments, and further documentation may be provided in an adjacent file.
The main challenge with documentation is that it easily gets out of the sync with the actual thing it is supposed to document. The only way to make it work is by keeping these two together.
Also, the code comes first, then comes the documentation. Otherwise we end up writing about nonexistent features in the documentation and that's not a good thing.
I try not to write over the subject
I've found out that it is easy to fail writing about any subject by writing very well about a different subject. Although I usually then do the inverse in some another document, this becomes a problem for the reader because the titles and texts do not match.