Does anyone else start new projects by writing out a readme detailing how you want the tool to work? I think I've come to depend on this technique to help me clarify what exactly I want to build.
2 years ago 路 馃憤 nintron, angryboyd, devyl
duh https://gordonguthrie.github.io/literatecodereader/ 路 2 years ago
https://gordonguthrie.github.io/literatecodereader/
last week and over the weekend I wrote a CLI to generate architecture documents (most document systems for programming languages generate API guides, how to use libraries, and not architecture) and but my documentation with that. (Obvs I couldn't do it documentation first as it didn't work) Would welcome your thoughts on it. 路 2 years ago
for CLI tools writing the help file and flags and flag validation (including if-this-then-that-also and if-this-not-that works rly well 路 2 years ago
@angryboyd If it's a super-simple utility without subcommands or flags, I'll generally have a clear picture of what I want the utility to do, how I want to invoke it, and how it should be structured. But anything more complicated and I start needing something in writing to force myself to iron those things out ahead of time. E.g., this evening I sat down to code, realized I didn't really know where to start, so I started with writing out the readme's usage and configuration sections, which helped me figure out the next steps I needed to take.
I expect the documentation will evolve with the code, of course. 路 2 years ago
I've never heard of this before. The readme always seemed like something you add at the end. I'll have to try it out. 路 2 years ago