File structures are definitely an art. A file structure has to advocate for both its application and its users. With open source, and the internet more generally, so much of it is connecting with people you may never meet and their creative generations. It’s a major communications challenge. I think this is part of why Ruby is so expressive – and so focused on being ever more expressive, and so common in open source (and so integral to sites that enable open source like Github) as a result.
As a total ruby n00b, I’m never quite sure whether it’s me or the file structure when I’m confused about what to do with a repo, app, etc. I’ve found READMEs critically important to help me conceptualize ‘what do I do with this thing – and where/how can I run it to figure that out.’ I found Zach Holman’s “Bubs” a paradigm of productive simplicity in this regard. Obviously, it’s not the most complex and layered app in the world, but it’s a gem that allows your command line text to appear in bubbles. Fun and games! I was pretty excited. Not only is it easy to figure out and use right away, but also structurally it’s quite easy to read the instructions for how to do this. The more I learn, the more I realize that so much of coding is learning to read code and documentation really well, so it’s valuable when a creator helps you do that. There are two folders in this file structure, a ‘bin’ and a ‘lib’. There are five documents, ‘.gitignore’, ‘LICENSE.md’, ‘README.md’, ‘Rakefile’, and ‘bubs.gemspec.’ One thing I found interesting is that only the latter five documents were created by Holman. The ‘bin’ and the ‘lib’ were created by open source contributors. Perhaps as a result, it’s harder for me to understand specifically what they’re doing in those structures, though the meta-text explaining the objective of the folder aids somewhat. This helps me realize that it’s important to set your file structure down clearly before open sourcing, because otherwise you run the risk of letting other people make your code messier. It’s kind of like database design, in the sense that you need to design for the future, and anticipate use cases differently from the ones you are currently using to problem solve. As a beginner, I think it also has to do with having a very clear sense of what the purpose of each element is, and where it should live as a result.
For file structure dessert, a quote from Ted Nelson, definitely a founding father of the internet, from the article in which he coined the term “hypertext”:
“THE KINDS OF FILE structures required if we are to use the computer for personal files and as an adjunct to creativity are wholly different in character from those customary in business and scientific data processing. They need to provide the capacity for intricate and idiosyncratic arrangements, total modifiability, undecided alternatives, and thorough internal documentation. I want to explain how some ideas developed and what they are. The original problem was to specify a computer system for personal information retrieval and documentation, able to do some rather complicated things in clear and simple ways. In this paper I will explain the original problem. Then I will explain why the problem is not simple, and why the solution (a file structure) must yet be very simple. The file structure suggested here is the Evolutionary List File, to be built of zippered lists. A number of uses will be suggested for such a file, to show the breadth of its potential usefulness. Finally, I want to explain the philosophical implications of this approach for information retrieval and data structure in a changing world.”