Hey, help me out... I want the #Spritely Golem demo to be as understandable as possible. I know, I haven't written all the docs yet, but what's easier for you to read:
- All in one file, like this: https://gitlab.com/spritely/golem/blob/master/golem.rkt
- Split into multiple files: https://gitlab.com/spritely/golem/tree/breakup
Pls let me know! Your #bikeshed feedback appreciated!
whether or not to split seems split, but I did know I was asking friends to help me paint this #bikeshed
@cwebber I'm a big fan of the all in one file version for tutorials and such
@cwebber All in one file is easier to read as long as its not too long, but I prefer when it's split into multiple files. However, in the latter case, you could use conventions of racket packages so that the entry point is easier to recognize.
@cwebber
A readme would be delightful.
@Just_a_Galadin Yes that's coming soon :)
CC: @storm
@cwebber All in one file.
@cwebber Single file is easier to scan through, if kept small.
Having said that, I'd assume that people will use the demos as boilerplate for starting their own projects, so I'd organize it however I think the project should be structured. If that is multiple files, then I'd include a README with notes about what is where.
@cwebber What about a README where each chapter/section is also a separate file that just is included in the main file?
@FiXato are you asking for literate programming? because it sounds like you're asking for literate programming ;)
@cwebber
I usually prefer the one file approach because it's easy to scan through. A multiple file approach requires a tutorial in which you can have the reader create files on the go, otherwise you don't really know where to start, in which order to read them, and why they're here. Anyway your project looks really cool, I'm glad someone is picking up #Racket to make such an ambitious project. Good luck!
@m455b @euhmeuh I guess that seems to be the community consensus at the moment so I probably should go with it. And for now I agree it's easier.
The main concern I have is that *future* demos might be much larger and need to be split into multiple files, and thus it might be easier to do so in advance. I dunno.
@cwebber I'm also constantly trying to find protocols to learn how to implement without already-made libraries for any given protocol and I find the hardest part about getting protocols down is the lack of documentation, lack of examples of how to implement (again without protocol X library) it in a language.
If I ever get a job doing technical writing for APIs or protocols I'm def going to ask devs to provide implementation examples
@m455b I guess what I can also take away from your post is I should provide a Spritely demo that is ONLY a "extremely lean AP implementation" demo, without any of the "level up the fediverse" stuff the rest of Spritely is trying to do, completely documented as a tutorial?
@cwebber that sounds great!
It's like me looking at a protocol going "oh this is cool"
Docs: use protocol by doing this:
(require protocol-x-library)
(protocol-x-library::connect-to "mastodon.social")
And then me being like... But... But... I wanna know how to make my own :'(
This isn't directed at any of your stuff by the way.
Just a perspective from a computer enthusiast like me who doesn't know what he's doing or talking about haha
@cwebber and again, it all depends on your targetted audience, and completely clueless people like me may not be on that list if you are aiming to get developers who may actually get shit going.
@cwebber yeah why not docs first implementation 2.?
Also if they are so small they should be easy to implement in different languages? I think a lot, like a lot of people don't have the mindset of functional programing only. That's why having js or python (plz!! Python 😊) or any other c style implementation as well would help many people.
One file: +++
One file but if it gets too big multiple files: ++
Multiple files: ++
And yes, adding a README/documentation, ack :)