Follow

Hey, help me out... I want the 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: gitlab.com/spritely/golem/blob
- Split into multiple files: gitlab.com/spritely/golem/tree

Pls let me know! Your feedback appreciated!

One file: +++
One file but if it gets too big multiple files: ++
Multiple files: ++

And yes, adding a README/documentation, ack :)

whether or not to split seems split, but I did know I was asking friends to help me paint this

@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.

I tend to like 1 large file best. Especially if the sections are separated with headings.
@cwebber Thus far, it is less than 500 lines, so a single file is still acceptable. Much bigger and it becomes much harder to keep things in mind. You have a nice small number of separated files, which is easily managed and helps with comprehension. I think it is easier to understand that way.

CC: @storm
@cwebber If I was unclear, I was saying that the multi-file version is easier to understand, and that the larger it gets, the more the advantage goes to the multi-file version.

@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 @euhmeuh just gotta have a least one so people understand it better.

That way you have an easier means of comprehension to move onto harder things

@cwebber @euhmeuh so you build a comprehension with the single file, then you can take that comprehension to harder things that have multiple files

@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.

Sign in to participate in the conversation
Octodon

Octodon is a nice general purpose instance. more