|
Welcome to MUGS ⚄♠♞🏹 (Multi-User Gaming Services)! | github.com/Raku-MUGS | v0.1.2 has been released! (github.com/Raku-MUGS/MUGS/blob/mai...v0.1.2.md) Set by japhb on 14 May 2021. |
|||
| japhb starts documenting details of making a new MUGS UI type ... *winces at just-documented mess* ... EDD (Embarassment Driven Development) takes over ... HACK HACK HACK ... | 00:35 | ||
| OK, have now implemented `mugs-tool new-ui-type` to create a half-decent skeleton for a new MUGS UI repo. | 08:22 | ||
| Work so far documented in github.com/Raku-MUGS/MUGS/blob/mai...ew-ui-type | |||
| I'm using the creation of the Pop UI repo as a concrete example to follow. | 08:23 | ||
| raydiak | please please forgive me and remember I'm nothing but well-intended, but I'm going to nag you about API, tests, and example code in the docs again, more explicitly: | 20:36 | |
| have a look at github.com/raydiak/Inline-Lua . I like what you've done, but I keep hoping to see code examples and API documentation like you see in that README (admittedly my markdown formatting and order of the sections could use some adjustment, but you get the idea)...Pop also does an excellent job of this. literally everywhere across all of the many MUGS docs where they could have some actual code, | |||
| there's just XXXX or dancing around the question with "read the existing code" or paragraphs of English with no Raku | |||
| imo code examples and API docs should be at the top of your list. small self-contained examples make it feel real to programmers, and are also a good starting point for tests (I literally copied those 3 examples in my synopsis straight into the .t) | |||
| the other way around, writing tests also helps define your API, and serve as short clear examples of usage. if it can't be easily written as a short one-to-few-lines test and/or example inlined in a doc, it's something that could likely use improvement | |||
| API docs force you to start making concrete choices about the official API, which is something you want to do before people (including yourself) build on top of it, or else you'll end up with a mess of different API versions and alienated users (again, including exhausting your own self) | |||
| waiting until later to formally define your intended API will force you to later make broad sweeping changes across your multiple codebases. chasing a moving target like that is a lot of tedious fiddly error-prone work | |||
| I suspect you've deferred these things because you aren't sure or don't want to commit to a particular structure yet, but that planned structure is more important than a nascent implementation that spins around in different directions instead of moving deliberately towards a clear goal. you can't really expect users or even contributors until you have a stable and clearly-defined API, even if it's not entirely | |||
| implemented yet. | |||
| the specs and tests coming *before* the implementation is usually a really good idea for many reasons, which is why it's mostly how rakudo was/is developed. if you don't sit down and clearly plan and map out something of this scale ahead of time, you're very likely to end up with a really big mess. if you can't communicate it clearly in short, clear, concise tests and docs, you know you haven't planned it well | |||
| enough yet | |||
| japhb | I hear you, and those are all fair points. | 20:52 | |
| Sadly there are only so many hours in the day, and only so much I can do in that time. | 20:53 | ||
| Part of the problem is that my goals are very ambitious, and the problem space is deeply fractal. | 20:54 | ||
| I had hoped to have some momentum before needing to get a $dayjob again, but perhaps you are right, and there's just not enough there yet. | 20:55 | ||
| I am saddened, but I want to thank you for your honesty and directness; I appreciate it very much, and I know that it is nerve-wracking to give people tough feedback. | 20:57 | ||
| raydiak | I'm really sorry, I know it's a disheartening to hear less than positive things. Sometimes though, I think in communities that are *too* kind, where someone could learn something they just get silent judgement. It's happened to me several times. But I know it's a big project, and you need contributors, and this is how you get them. like if I had time to help more than working on a JS game in the background of | 21:10 | |
| your real work, I wouldn't know where to start. if there were a bunch of failing tests for unimplemented features, I'd know exactly what needs to be done and how it's expected to present itself and behave | |||
| japhb | Interesting. It hadn't occurred to me to write failing tests as a method of getting contributors. | 21:14 | |
| raydiak | it's how we did roast, iirc. then there was some mechanism for "these tests are actually expected to pass and should run on install" vs "these tests are spec but nothing actually passes them yet" | 21:15 | |
| japhb | Well, Audrey used to trade implementation for tests. | 21:18 | |
| raydiak | test-driven development is also often used in pair programming when one person is acting as the designer and the other the implementer, designer writes failing tests and implementer writes whatever is necessary to pass them | ||
| japhb | And there were a couple ways of indicating that something would not work. | ||
| raydiak: I don't have a pair programmer though ... | 21:19 | ||
| raydiak | I know, you just think of "whoever random contributor perhaps even my future self" as the other half | 21:20 | |
| japhb | In my case, I was happy to trade implementation and docs for feedback, but ... I sense the impatience. | ||
| raydiak | if there's these easy kinds of entry points for people, they're more likely to pop up. there are times I could help some, and I doubt I'm the only one | 21:21 | |
| main point being, planned spec is really important, and tests are a great way to implement that | 21:22 | ||
| it's easy to think of tests as just QA or something, but really all of api spec/tests/examples/docs are all connected, mutually-reinforcing things | 21:24 | ||
| japhb | Fair, though I think it's also easy to write a lot of non-implementation and never actually write the implementation. Or to spend a bunch of time on tests only to realize that the API as designed has no natural efficient implementation. | 21:40 | |
| It's easy to TDD when you're writing the 15th copy of basically the same thing (so TDD for cookie-cutter websites? Sure!), but it's a lot less natural when you're exploring a space while you go. | 21:41 | ||
| raydiak | but you're wandering blindly through that space without a map, compass, flashlight, or companions for the most part, and that's going to doom the effort unless you're happy to do it all yourself for a very long time until you come up with a solid structure you like and then document it. and the code churn in the mean time is going to be a huge burden | 21:51 | |
| you're right it's not easy, and can in some cases lead to things which are difficult to implement. that's why rakudo has slow parts. but they are parts we wanted to exist even if making it all work isn't immediately easy or fast. and rakudo wouldn't likely exist in the fullness that it does now without roast, it'd be a much smaller subset of features or long-abandoned for lack of participation | 21:55 | ||
| japhb | Sure. I also don't have 20 years to work on it. I mean yes, I (think I) grok what you're saying. It's just not how I create successfully. For me historically, deep planning results in boredom pretty much right after finishing the planning and eventually moving on to something else. If I don't keep the design part of my brain involved on a *continuing* basis, the coding part loses all the -Ofun. | 22:02 | |
| I think for me the most influental programming book I had as a kid was Peter Norton's assembly language book -- and it was because he very explicitly said "The very first thing we should do is produce some output. And then make that output actually mean something. And then make it useful. And keep iterating, always having something new that you can *see*." | 22:04 | ||
| It's why the whirlpool development model appeals to me so much more than waterfall. | |||
| For some people, TDD actually seems to fulfill the goal Peter Norton was going for, but only if they do a tight write test-edit implementation-test result cycle. | 22:06 | ||
| Heck, one of the early lambdacamels write a program that basically forced that sequence on a per-test basis. | |||
| But, stepping into a different part of my work, I do see that it's difficult to figure out from implementation alone what a library designer intended. When I looked at the Pop repos, I read/skimmed through the API docs, and looked through the examples. But mostly that helps to get me a mental model before diving into the actual implementation to turn that mental model into real understanding. | 22:09 | ||
| None of which is to say that I don't hear the feedback, BTW. I get that my work method is not working for you. I will see what I can do to produce the things you've asked for. :-) | 22:10 | ||
| raydiak | fair enough, I definitely don't want to tell anyone how to create. I violate exactly the principals I'm talking about all the time (but I don't really expect any users or contributors) | ||
| it's not just for me specifically. I don't see you getting a ton of engagement without these things, though I'd love to be wrong about that. a combination of "I don't know what's going on in here" and "I don't respect this style", right or wrong, I forsee filtering out a lot of prospective participants | 22:15 | ||
| japhb | You're right, I'm not getting a ton of engagement (except for people who've spoken on this channel), though I always knew that could be a problem before I finished 0.2 -- it takes a certain mindset to enjoy someone else's infrastructure code before it supports something with intrinsic coolness. But I didn't want to wait for that big milestone before releasing anything, or I'd never make it. Release early, | 22:41 | |
| release often, neh? | |||
| raydiak | maybe when you're more decided about things and start solidifying the details in docs, tests, whatever, ask lizmat to put something in the weekly like "MUGS 0.2 is structually stabilized and well-specified, calling for contrbutors to implement NYI features/pass failing tests". give initially hesitant people a reason to take a second look | 23:04 | |
| japhb | Not a bad idea. I was planning to ask for a mention at each major milestone anyway, but the amount of yak shaving it's taking to get from 0.1 to 0.2 is truly epic. | 23:21 | |