beeware.github.io Update the BeeWare website

Hello! This is my initial update to the BeeWare website. It's nowhere near completed but I wanted to get this PR in early for your perusal. So far I've done at least the following:

Split About into multiple pages and moved the link to the header
Moved the "More than just code" section of About to /community/
Moved the Code of Conduct to the header
Added a dropdown to the header so we can include more information there without overwhelming the header
Moved Membership to / and updated the link
Moved the team list to the About page
Moved the Overview from Project to About
Moved the "What can you do to help?" page into /contributing/
Everything under /how/ is now under /contributing/ and linked in the text on that page, as well as the right gutter
Moved "Core team, and responsibilities" to /community/
(As well as the obligatory) and more!

I did not check the "documented" box below because I did not keep track of everything I did, as many things were merged and separated, and I started to lose track of where it all began. The list above covers most of it, but I'm sure I missed something.

Next steps

Update Projects to showcase Briefcase and Toga, and highlight the other active tools as per discussion with @freakboy3742
Move inactive apps to Attic
Create separate contact pages for Security, Code of Conduct, etc
Continue to streamline everything else.

That's what I have for now. Cheers!

PR Checklist:

[x] All new features have been tested
[ ] All new features have been documented
[x] I have read the CONTRIBUTING.md file
[x] I will abide by the code of conduct

Aug 02 '24 00:08 kattni

I restructured the Project page as discussed. It looks like a lot of changes, but it's primarily renames, as I had to move everything around to restructure things.

Notes:

I am certain there is probably a better way to do what I did in the Jinja, but it works! That said, please provide any feedback you have on doing this differently, etc.
I did the best I could with sorting through the data model files and figuring out what needed to go where. Let me know if I should have done anything differently there as well.
I feel like I missed one thing that you wanted to be considered an "Application" and not a "Utility". Please let me know if the Utilities and Application categories are correct.
The /project/ page currently has very basic CSS for the purpose of differentiating divs. I didn't dig into that yet because I want you to let me know if the layout and concept are what you're looking for before I jump into styling.
I updated the /project/ page title to "BeeWare Tools". "Tools" is growing on me as a replacement for "Project" in the header and as the page name. Let me know what you think.
Toga and Briefcase are displayed through an autogenerated group of "showcased" projects (through Jinja set, for, etc), so if you want to include more later, it's a checkbox in Lektor.
I ended up having to hard-code the "Applications" and "Utilities" category boxes, because I couldn't figure out a way to generate separate lists underneath the headers if I autogenerated the categories as well. Adding another category later would mean duplicating a block of code in "beeware.html", and updating a few references to the category name and URL. I don't know if I missed something about how those groups are generated that would have allowed me to differentiate them in the code. So if there's a simpler way to do this, I'm open to it, but this was what I figured out.
The /project/utilities page has no text content as of yet. There are a lot of places where I think text needs to be updated, so we can address this when it makes sense.
The "project-type.ini" and "project-type.html" files are now only used by Attic. I meant to rename them to "attic.*" before pushing, but now I figure it's worth asking whether this makes sense before doing it. As-is, it is confusing as to what they are for, but I don't know whether they are linked to anything else in Lektor etc, and I don't want to inadvertently break things in the quest for clarity.
I updated the "Projects" section on the homepage to show only showcased projects (which are now only Toga and Briefcase).
At the moment, the original /project/projects/ directory structure is a series of empty directories prepped for redirects. I intend to add redirects when we're closer to completed in case things move around in the meantime.
I am making a note here for myself as well: I will have questions about cleaning up labels and other behind-the-scenes stuff that isn't being used anymore, as to whether things should be left in place for posterity/structure purposes or be cleaned up.

Aug 03 '24 23:08 kattni

Visit the preview URL for this PR (updated for commit ea4e70a):

https://beeware-org--pr578-streamline-beeware-w-h9imfohd.web.app

_{(expires Sun, 11 Aug 2024 01:18:10 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: b0da44bc067e7d9a4255c77cb2c5fce572218cec}

Aug 04 '24 01:08 github-actions[bot]

This update addresses only the Project page layout, and the issue with an unnecessary data model being added. I will address the rest of the comments/concerns/suggestions later.

Aug 04 '24 17:08 kattni

Replies to your initial notes:

The box-and-background-color layout doesn't really work IMHO. I've got some ideas on other possible approaches, but I'm not sure of the best way to share ideas/iterate on mockups of a final layout - open to suggestions on how best to collaborate on this.

I pushed the update yesterday to match your later suggestion. Please let me know what you think, and if it still doesn't work for you, we can sort out a collaboration method.

Re-ordering the menubar items. It seems to me that "About" should either come much earlier, or much later (I'd lean towards earlier)

I shifted it between "Project" and "Community". Let me know if that works for you or if you want it to come first.

I'm wondering if the "More" item is actually achieving its desired goal. I guess the intention is to surface more to the top level without crowding the menubar... but it feels a bit like we're still crowding the menu bar, just putting it under a fold. I wonder if, instead of having a "more" item, we move those items under other headings (e.g., say, "code of conduct" under "community"), and then make the other headings pull down menus that provide shortcuts to notable "deep" content.

I can work this up and we can see how it feels. I think the way it works right now, the dropdown would always show up when you clicked the page link, as the page loaded, e.g. if you clicked "Community", you would load that page and see the dropdown at the same time. I'll see if I can figure out a different approach if that ends up seeming awkward, such as the dropdown only showing up if you click the arrow next to the page title or something of that nature.

I think there's still some re-org potential in the contributions page. The collapse of the depth is great - but the Contribute landing page is now a bit busy and unfocussed.

Agreed entirely. I have not taken a pass at this page yet, other than to shift contribution-related things to it.

If you want to catch up for a follow up chat on any of this, I'm at your disposal.

This would be appreciated. I'll reach out on Discord when I get to a point where it makes sense again.

Aug 05 '24 21:08 kattni

The most recent update is a demo of individual existing headers having dropdown menus attached. The way it's done at the moment, the page of the header loads separately from the dropdown, which I think is a necessity.

@freakboy3742 Let me know if you like this better than the "More" menu, and we can make use of it where it makes sense moving forward. The current dropdown items are not necessarily where they will end up - I split them up to where they are for the purpose of this demo.

Aug 07 '24 19:08 kattni

The most recent update implements collapsing content on the Contributing page, as a potential option for including more information, in a cleaner, less busy way, without loading up another load of subpages. I did not do it for the entire page, as this is simply meant to show what it could look like, if you are interested.

Aug 08 '24 23:08 kattni

The box-and-background-color layout doesn't really work IMHO. I've got some ideas on other possible approaches, but I'm not sure of the best way to share ideas/iterate on mockups of a final layout - open to suggestions on how best to collaborate on this.

I pushed the update yesterday to match your later suggestion. Please let me know what you think, and if it still doesn't work for you, we can sort out a collaboration method.

Definitely better.

The underlining on H1 titles is overkill; we're not using underlines anywhere else, so we can probably lose them. If this has been done to make the section headings stand out a bit more, this might be an area where having a background color block on the title might make sense - although that would also be inconsistent with other parts of the website.
I'm not sure the description of project types is adding anything. As it stands, it's making the layout busier, and it's not clear how they fit into the overall flow.
While the section headings are hyperlinks, there's no real call to action to suggest why this might be the case. There might be value in having an "... and N others" hyperlink after all the featured items in a section.
The explainer of "Beeware is a suite of tools etc etc" needs to exist; I'm guessing what might be what you're intending with the "copy here" section, but I don't know if it might fit better into the sidebar. The sidebar might also be a way to maintain a link to the attic without needing to give it placement in the "main" list.

Re-ordering the menubar items. It seems to me that "About" should either come much earlier, or much later (I'd lean towards earlier)

I shifted it between "Project" and "Community". Let me know if that works for you or if you want it to come first.

I think it makes sense to be first. Unless you're coming to the project already knowing what Toga and Briefcase are, your first questions are likely to be "what is this thing?".

I'm wondering if the "More" item is actually achieving its desired goal. I guess the intention is to surface more to the top level without crowding the menubar... but it feels a bit like we're still crowding the menu bar, just putting it under a fold. I wonder if, instead of having a "more" item, we move those items under other headings (e.g., say, "code of conduct" under "community"), and then make the other headings pull down menus that provide shortcuts to notable "deep" content.

I can work this up and we can see how it feels. I think the way it works right now, the dropdown would always show up when you clicked the page link, as the page loaded, e.g. if you clicked "Community", you would load that page and see the dropdown at the same time. I'll see if I can figure out a different approach if that ends up seeming awkward, such as the dropdown only showing up if you click the arrow next to the page title or something of that nature. ... The most recent update is a demo of individual existing headers having dropdown menus attached. The way it's done at the moment, the page of the header loads separately from the dropdown, which I think is a necessity.

@freakboy3742 Let me know if you like this better than the "More" menu, and we can make use of it where it makes sense moving forward. The current dropdown items are not necessarily where they will end up - I split them up to where they are for the purpose of this demo.

I think the menus work organisationally (better than "more", anyway); but I'm not sure the implementation is quite right. The expansion arrow is a small target, and it took me a couple of tries to get it to work. The i18n dropdown is a "click to open dropdown, click to select target"; I think that might be a better approach for about and community as well.

The most recent update implements collapsing content on the Contributing page, as a potential option for including more information, in a cleaner, less busy way, without loading up another load of subpages. I did not do it for the entire page, as this is simply meant to show what it could look like, if you are interested.

Yeah - definitely not a fan of expansion for content. IMHO it's the worst of both worlds - requires an extra click to navigate, but doesn't simplify the page when it's visible.

Aug 09 '24 02:08 freakboy3742

Following up from a conversation on Discord: here's a mockup of what I had in mind for the design of the project page. It's not that far removed from what is there right now:

Ignore the top bar menu; this is for the purely for the purposes of the project landing page. I'm also certain there's inconsistencies in exact spacing and font choice by virtue of using a mockup tool; the intention is to highlight clear space between the three "sections", and "more featured" content being larger/more prominent. Other than that, the major changes are:

Using the sidebar for the explainer/context; and including the attic as an link in that content
Making the icons more prominent, which gives a bit more space for text around them (which I think helps with the general layout)
Making the text explaining Apps and Utils more cohesive as a "featuring... and more!" kind of flow
I've filled in some of the placeholder content that hopefully fills in the gaps, and should be compatible with the existing data model (although you might need to play some tricks, like having ", including:" be static content appended to the database content)

I'm also not completely tied to any of this - if you've got ideas on how this could be improved, I'm all ears.

Aug 21 '24 01:08 freakboy3742

@freakboy3742 I have a couple of questions/suggestions before I push the current state of things.

It seems like "Project" should be called "Tools", but that does lead to other updates needed. I'm referring to the page and to the actual header menu name. Let me know what you think. I'm already doing a boatload of redirects, so another one is negligible. The translations would have to be updated though.
I updated the data model for the Applications/Utilities page to have a "Project Page Description" that is the longer-form description. Using all the content except "including" as the "short description" seemed a bit long as a page description under the header on the page itself. So I added another field to the page to add the longer-form version. If this is not acceptable, let me know. (If you want to wait until I push to see what I'm talking about, that's also fine. But I think my description is enough to explain why I opted to do something you suggested against - and that is why I am bringing it up here.)
There is only one "application". I currently have it so that it checks how many items exist in the project query, and if it is more than 1, it includes the "..... and others", otherwise, it does not. I feel like "and others" when there is one is a bit clunky and odd, but let me know if you disagree and would rather it simply be hardcoded to be there no matter what.

Everything else we discussed is more or less in place and updated. These are a few items we did not discuss, so I wanted to bring them up before continuing.

Aug 22 '24 23:08 kattni

@freakboy3742 I have a couple of questions/suggestions before I push the current state of things.

It seems like "Project" should be called "Tools", but that does lead to other updates needed. I'm referring to the page and to the actual header menu name. Let me know what you think. I'm already doing a boatload of redirects, so another one is negligible. The translations would have to be updated though.

I'm not sure about this one. To me, "tools" are the things that you actually touch to do things - so Briefcase might be a tool - but a library or template or support package is something else... it's not really a "tool". The existing text on the project page reinforces that kind of distinction - "BeeWare isn't a single tool or library - it's a collection of projects". To that end "Project" (or maybe "Projects") would seem to be the better fit.

I updated the data model for the Applications/Utilities page to have a "Project Page Description" that is the longer-form description. Using all the content except "including" as the "short description" seemed a bit long as a page description under the header on the page itself. So I added another field to the page to add the longer-form version. If this is not acceptable, let me know. (If you want to wait until I push to see what I'm talking about, that's also fine. But I think my description is enough to explain why I opted to do something you suggested against - and that is why I am bringing it up here.)

That sounds perfectly reasonable to me - it's nice if we can re-use content when we can, but we don't have to be completely dogmatic about it for the sake of "database minimalism".

There is only one "application". I currently have it so that it checks how many items exist in the project query, and if it is more than 1, it includes the "..... and others", otherwise, it does not. I feel like "and others" when there is one is a bit clunky and odd, but let me know if you disagree and would rather it simply be hardcoded to be there no matter what.

Podium is the only application on the current website taxonomy; but Cricket, Bugjar, Duvet, and Galley would all fit under the category of "Application" rather than "Utility" to my mind, as they're end-user apps. That should still leave plenty of content for the utilities page.

Aug 23 '24 04:08 freakboy3742

Redirect script wasn't quite right. Fixing.

Aug 27 '24 18:08 kattni

@freakboy3742 This should now be much closer to where we discussed. I've removed the functional menu changes, and moved the discussed items into appropriate locations. The Project page now better reflects your mockup.

A couple of notes:

The Utilities page needs a "long-form description", by which I mean, the content that goes in the gutter (grey sidebar box). The Applications page has one, I think it makes sense to have on Utilities, but I do not know what to include for that content.
The Bee Team page is not rendering the team photos for me locally; I don't know if this is because I moved it and missed something tied to it, or for a similar reason that the icons for the social media things don't render (e.g. they render when the site actually builds, but not on the lektor server version). Let me know if I missed something here and have an item to fix with it.

Please take a look when you get a chance, and let me know what you think.

Aug 27 '24 21:08 kattni

@freakboy3742 Hello! I've updated all of the URL references in text to match the restructure.

I will follow up with you on the rest of it next week. Cheers!

Feb 07 '25 22:02 kattni

@freakboy3742 I updated the Projects page layout to match the layout on the Applications and Utilities pages.

I also fixed a layout issue present on the Utilities and Applications pages, visible on MacOS and Firefox on Windows, but not Edge on Windows. I imagine it wasn't visible to you either, or you would have mentioned it. The spacing between elements was different based on the length of the description. Everything is now evenly spaced regardless of line-wrap.

Feb 17 '25 19:02 kattni

I think there's some cleanup required around the data models and templates tied to the project pages. I flagged the generic nature of "beeware.html/beeware.ini" in an inline comment; but I think that's part of this general problem - that there's still pieces of older "deep nested" data model in the repo after the refactor. The real marker of this is that we're removing a layer of depth/complexity, but adding a data model... at the very least, I would have expected to see one data model removed, if not more than one.

@freakboy3742 I think I've completed everything else in your change request.

At this point in this update, I'm going to take you up on your offer to step in. I did the best I could with my limited understanding of Lektor. I definitely do not understand Lektor well enough to clean up the data models without feeling like I'm starting over from scratch.

I'm happy to do any more updates I'm capable of doing, if you find anything else. Please let me know.

I'm super excited to see this merged, but I understand that your final steps may not be a priority. I'll be keeping an eye on this for any updates.

Feb 17 '25 19:02 kattni

@freakboy3742 You're entirely welcome! I'm so glad to hear that you're happy with the results. I'm definitely excited!

Thank you so much for explaining how you simplified the data models. I was genuinely curious how that was going to work. I'm quite glad I handed it over to you, I would not have been able to sort that out. Thanks for picking up the final steps for this!

I went through each of your commits on GitHub, everything looks good to me. I pulled your changes and went through the updated site, and you've added the content everywhere I remember it being needed as well.

I'm not seeing anything else that needs to be updated. This is ready from my end. Let me know if you need anything else from me!

Feb 21 '25 20:02 kattni

Awesome - in which case, 🚢 :shipit: !! Thanks again for this mammoth contribution!

Feb 22 '25 03:02 freakboy3742

Update the BeeWare website - WIP

Next steps

PR Checklist:

Notes: