Some general questions about functionality, documentation, examples, etc.

[kfogel]

Hi, @yshng. I just looked at README.md and index.html. Am I correct in thinking that the latter is intended as an example of what one course's syllabus might look like? If so, it might be better to call it example-output.html or something like that.

Next question: what is the input that gets transformed into that output? In other words: the output is one particular concrete representation (complete with layout, fonts, colors, and so on) of an abstract data object -- a syllabus. Now, in README.md, you define this abstract object pretty clearly: you say a syllabus has a course title, course description, various fields for meeting patterns, etc. But one thing I don't see in that definition is any slot that would hold the per-meeting reading assignments -- yet in the HTML, each meeting does have those assignments. So your data is, seemingly, not quite matching up with your documented structure (or "data schema" if you prefer) at the moment.

I think a good way to keep your abstract schema aligned with what you're actually showing to users is to cleanly separate the structure of the content from the displayed form of that content. So, for example, if you had a JSON format for a syllabus, then each actual syllabus would be a JSON file (or would be one item in a JSON file containing multiple syllabi), and you could validate that JSON: you could have code that would issue warnings like "WARNING: Syllabus has meetings with no reading assignments" or whatever. And to get an HTML file to send to a browser, you'd process the JSON and generate the HTML file(s).

[kfogel]

Oh, interesting: you had sample.html for a little while, but in commit 7d20b68c4e31a you actually renamed sample.html back to index.html. But I can't tell from looking at that commit why you did so (some suggestions for writing good commit messages are here FWIW).

[yshng]

Thank you for these comments, I did think that perhaps more specification was needed in the schedule portion of the syllabus, but trying not thinking ahead to what kind of storage method I was going to be using, I ended up trying to stay more general.

I have never done any object oriented programming before, so I don’t yet know the affordances of objects, JSON, etc. My previous experience is in a language that no one uses (Racket) where I was doing functional programming and defining all my own data structures, and in C where I mostly recall doing a lot of manual memory allocation and using pointers to put together data structures. In any case, I do think I can be more rigorous in specifying all the component parts of the schedule in the abstract, but wondering if I should start thinking about this in more specific terms of something like a JSON file. Part of my motivation in working up a sample syllabus was to hold the data structure somewhere, even in terms of output, before making decisions about how to format the input - I thought you were advising holding off on this particular decision the last time we spoke, but perhaps I misunderstood!

And yes I went back and forth on naming the file as a sample, before renaming it index.html as a kind of placeholder. I could’ve said as much re: placeholder in my commit message. I’m definitely still learning the art of a good commit message - thanks for the link!

On Thu, Jun 13, 2024 at 11:00 AM Karl Fogel @.***> wrote:

Oh, interesting: you had sample.html for a little while, but in commit 7d20b68 https://github.com/yshng/canonize/commit/7d20b68c4e31a0792f65c0e4a0584ebac948cee4 you actually renamed sample.html back to index.html. But I can't tell from looking at that commit why you did so (some suggestions for writing good commit messages are here https://code.librehq.com/ots/meta/-/blob/main/CONTRIBUTING.md?ref_type=heads#writing-commit-messages FWIW).

— Reply to this email directly, view it on GitHub https://github.com/yshng/canonize/issues/1#issuecomment-2166092168, or unsubscribe https://github.com/notifications/unsubscribe-auth/AZXCXXWHGR5N7E7XPSO7G4LZHG6YHAVCNFSM6AAAAABJIWJDRCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNRWGA4TEMJWHA . You are receiving this because you were mentioned.Message ID: @.***>

[kfogel]

Oh, JSON isn't really about object-oriented programming; it's just a format for expressing data layout -- a format that can be parsed (in contrast to the prose in the README, which can't so easily be parsed). You could as easily use XML or some other format, but JSON is sort of the norm these days so I would recommend just going with that for now.

Part of my motivation in working up a sample syllabus was to hold the data structure somewhere, even in terms of output, before making decisions about how to format the input - I thought you were advising holding off on this particular decision the last time we spoke, but perhaps I misunderstood!

Not at all -- I think you have now done that exercise and it has served its purpose! You're now ready to actually define the schema in a formal way. The schema may continue to evolve over time, and that's fine. By creating the sample syllabus, you've figured out the basics of what a syllabus is (as far as this project defines it), and so now you're ready to express what a syllabus is in a way that the machine can understand, and maintain it in that form for the rest of the project.

[yshng]

Ah gotcha, I only knew what JSON stood for so I was misled by the name. Glad to be moving forward!

[kfogel]

Think of JSON as "like XML, but new and different".

[kfogel]

And I should add: maybe we won't stick with JSON forever, and that's okay -- perhaps it will be an SQL schema eventually, or something. The main thing is to formalize your definition of a syllabus into something parseable, and then generate the HTML pages from specific blobs of JSON that match your standard of what a syllabus is.

So even more specifically: I think a good next step could be to express what's in that HTML file in a JSON file. Don't worry about the HTML layout and styling and whatnot -- we'll add that all back in at the HTML-generation step. Just capture the raw syllabus data, in JSON.