pba-content

pba-content copied to clipboard

          We want to _remove_ per-module style in favor of global only style, with tweaks for specific elements via tailwind and/or other plugins.

@wirednkod wdyt about this globally? I think someone wanted the opposite earlier... @BradleyOlson64 IIRC

Originally posted by @NukeManDan in https://github.com/Polkadot-Blockchain-Academy/pba-content/pull/772#discussion_r1274287645

This is such an arbitrary requirement.

Stylized CSS elements is a huge part of any web design.

I don't understand what you are trying to gain by limiting the ability to customize elements.

I get that it is constricting the true unlimited pallet we have to use CSS that indeed you are adept in, more than most content creators for the PBA :magic_wand: But we are not making a website.

We are making a set of documentation for learning from, perhaps also expanding into some MVP for a custom LMS like Canvas you may have used before. The web analog perhaps best is MySpace vs Facebook: we lean into an intentionally restricted set of styles and abilities for the content creator (like Facebook) for many reasons, here are a few key ones:

• "A consistent tone and style makes your content easier to read, reducing your users’ cognitive load and increasing their confidence in the content’s authority." ^1
• Maintainability and sharing customization options for everyone.
  • These are not your slides, but an integral part of a large whole that must be maintained by others long term.
  • Global styles help reason well about global style changes effect across all slides where as things like https://github.com/Polkadot-Blockchain-Academy/pba-content/pull/772#discussion_r1274287645 are actively overriding this and maintainers just need to discover where some custom override is taking place on a case by case basis. It's not scalable and creates unneeded overhead for them.
  • If someone's needs are not being met in such a way that a per slide override to tweak behavior like a module level override does, indicates we need to consider a global style to allow for your use case and support it and make it an example of style to copy & paste in our instructor facing slides to learn from and use as templates.

In providing my perspective, I believe that incorporating a global outlook into the slides is appropriate as it maintains uniformity. Simultaneously, it is essential not to restrict the presenter's ability to customize the lecture slides according to their preferences, as long as it aligns with the overall guidelines.

While I don't advocate for extreme deviations from the original approach, it is crucial to acknowledge that exceptions can exist. I respectfully disagree with some of the points raised, and I shall elucidate my reasons:

• Regarding the statement, "But we are not making a website.... The web analog perhaps best is MySpace vs Facebook": Our endeavor involves creating a website with multiple authors in a structured manner, which is why we utilize web tools.

• Concerning the assertion, "These are not your slides, but an integral part of a large whole that must be maintained by others long term": The slides belong to the lecturer and are considered their intellectual property. It is their prerogative to share them with the PBA; I believe they should possess the capability to make reasonable adjustments without straying too far from the designated format. In subsequent PBA iterations, other presenters can adapt the content and style accordingly.

In conclusion, it is beneficial for presenters to infuse their ideas into the slides, both in terms of content and style. Such individual contributions may even evolve into established conventions over time. Therefore, we should strike a balance by offering limited customizability while providing helpful tools to facilitate usage, such as mermaid, d3 charts, and tailwind, for instance.

End of the day, there are a bunch of styles applied across the slides, which really dont make sense in a lot of contexts.

I mean, the CSS that brought up this thread was to fix an already opinionated way of having bullet points.

Let's compare the look of the two.

Before:

After:

Look at how stupid the padding / margin looks on these bullets in the context of this slide. Would you ever NOT customize the styling here?

Please look at the custom CSS file:

https://github.com/Polkadot-Blockchain-Academy/pba-content/blob/main/assets/styles/custom-classes.css

Is there really anything in there which is rocket science? If we have anyone in the academy (student or lecturer) who cannot figure out these styles, they should probably not be here.

Also note that all of these styles are written to be reusable OR specific to a niche diagram / slide.

Installing tailwind does give access to some more tools, but does NOT act as a solution for styling, nor is it really any more efficient or easy to understand.

Whatever your mental model is of the bad-ness of custom CSS needs to be adjusted, and you should rely on people's judgement who have much more experience using these tools.

Concerning tailwindcss, i would agree and add, that the only thing, that I can say it adds as value, is adding simple customization inside the md/html (className), instead of creating a