Closed zhakk-harn closed 3 years ago
b2renger
commented
3 years ago A nice thing would be to have some kind of naming convention :
We should also have a readme template to fill in :
zhakk-harn
commented
3 years ago Double yes. I'd add a gif demoing the thing in action (unless impossible) at the top of the readme.
To put the peripherals in the name I'd suggest going with "X-with-Y-through-Z" where X is a task achieved with Y through the Z communication protocol. Although I suspect that only the two of us will care about the communication and that's it is more noise than signal to put it in the title rather than just the dependencies. But because we won't have that many I don't really care that much about using either "X-with-Y" or "X-with-Y-through-Z"
Here is an example of the "flat" way : https://github.com/vercel/next.js/tree/canary/examples In hindsight it's more geared towards user who knows what they want before coming to the repo by either typing the name of the framework + the piece of tech in a search engine or Ctrl+F for the piece of tech in this repo. The ability to get a glance at what's also available being a nice it is also just a bonus and not the main feature. conclusion : flat is a no go
So, going hierarchical, I was thinking of organizing by folders depending on what they enable you to do :
but it gets blurry extra fast, I could argue that a lot of web is interactive content and if the content is rich enough (and done using \<canvas>) it would be expected in the "interactive graphics". Not to mention that we're soon going to put unity/processing/touchdesigner in the same folder but they'll also spill out because sure they overlap but they are not the same either.
So, unless anyone disagrees, I propose we go hierarchical by tech/framework/lib the downside is that they need to know which tech enables them in which way but that's going to get mitigated fast if the peek into the folder and see all the tasks achieved by said tech which will show either an emerging theme or a versatility.
On the point of using two tech in a project, I'll argue that the simpler tech should just be absorbed in the more complex tech (e.g. establish communication between unity and arduino should go in the unity folder). Staying with this example we could have an empty folder in arduino pointing to its twin in the unity folder.
Going this way we could save a little more time on writing if we use template readmes at the top of the tech folders since the installation, run and part of the deps are going to remain the same between project. I would make it tedious to rework the structure but I think @b2renger covered everything nicely and we shouldn't have to move it.
b2renger
commented
3 years ago We could have a big hierarchical table of contents at the beginning of the readme pointing to subfolders with relative links. This way we can Ctrl + F like crazy ! In this table we could put things into more words than just a naming convention but it must stay short enough.
zhakk-harn
commented
3 years ago Table, as in : https://www.tablesgenerator.com/markdown_tables ? Although, if we mix what I was thinking and what you just wrote it reminds me of the "awesome" repositories like this one : https://github.com/ocaml-community/awesome-ocaml
b2renger
commented
3 years ago yes a bit like those repo. Not really a table more a list though I actually committed a change to the main readme so that you can see what I meant, I just forgot to reference the commit to this issue (sorry for that)
zhakk-harn
commented
3 years ago alright, I'm sold.
If we do it "flat" and have all the boilerplates at the top level we can expose everyone to everything so we'll enable the curious.
But if we structure that like say :
we'll have something which easier to navigate.
So far my idea is to go flat and then switch to hierarchical if we ever get to 12+ boilerplates (honestly with the different flavors of processing and arduino it can go fast)