Websites improvements initiative - Step 1

[marcuspollio]

Context

FreeCAD's websites infrastructure has been developed organically over the years. It is made of various parts which interact differently both for end-users and content contributors. Moreover they do not communicate easily with each other, they have a different logic data and code-wise and incoherent visual designs. This contributes to a difficult maintenance and is not advantageous for the project's impact. Some qualities can however be retained from the present state, which can serve as a useful experience and reference for future improvements. Early 2024, an initiative to review and improve the situation was launched by some Design Group contributors ¹. This is the first step in a multi-year initiative.

Proposal description

This first step has two simultaneous objectives : update some parts of the infrastructure and lay the foundations for improved guidelines, documentation, curation and maintenance effort of the whole FreeCAD websites infrastructure.

Unification of the Homepage, News blog and Developers Handbook

The main goal of this first step is to update and unify most informative parts: the Homepage, the News blog and the Developers Handbook. This unification aims to provide a single structure for these three currently disconnected bits: simple to use, easy to augment and edit content, inter-connected, great flexibility to accommodate FreeCAD's growth and evolution, and as minimum maintenance as possible.

On the Technical side, all content is version-controlled, stored in simple Markup files (Markdown) and data interchange or serialization format files (e.g. JSON, YAML). A Static Site Generator (Hugo) and a server-less Content Management System (Sveltia) are used, making it easy to separate content from Theme and Configuration. More architecture choices and technical details can be read on the linked prototype below or can be requested in subsequent discussions.

A prototype of the above setup is currently under development ². This grant will allow to move beyond the prototype phase so larger testing can be performed and potentially future deployment as well.

Foundations for improved guidelines, documentation, curation and maintenance

While the current effort is the start of a long and hopefully lasting initiative, improvements on the collaboration and development aspects are also expected. In recent years, FreeCAD has seen multiple initiatives geared towards fostering collaboration and the establishment of several interest groups bridging the gap between users, professionals and hobbyists, designers, non-code contributors and developers. This initiative seeks to promote comparable effects, specially in regard to website guidelines, documentation (FreeCAD use and code) and overall care for its user-facing infrastructure.

An informal group is currently contributing to the development of this initiative ³. This grant will allow to move beyond the informal phase so lasting benefits can be achieved in setting up a robust interest group in the open.

Step 1 and beyond

This Step 1 consists in completing the Alpha and Beta phases detailed below of the website unification prototype while setting up the foundations for greater collaboration. The pinnacle of this first step is setting up the unified website on a sub-domain (called here Release Candidate phase) so that it can be tested by a larger audience.

If this proves successful, a Step 2 will then begin: improvements, content call and polishing during the RC phase, transition to final production deployment (also archival of current websites), continued development and maintenance, planning of next steps (e.g. User documentation, aka Wiki migration, APIs docs, FPA website, etc.).

Deliverables

Alpha Phase: features parity

Task	Time estimation	Compensation	Collaboration
Homepage	2 days	200 €	Design with DWG, Approval by FPA
Features page	1 day	100 €	Design with DWG
Port blog to News section	5 days	500 €	Design with writers
Community and Events page	1 day	100 €	Design with DWG
Port Dev Handbook to Contribute section	3 days	300 €	Design with DWG & CQWG
Telemetry page	2 days	200 €	Design with DWG
Donation page and workflow	4 days	400 €	Design with DWG & FPA
Authors credit (articles + images)	1 day	100 €	Design with DWG
Footer	1 day	100 €	Design with DWG
Archives pages	1 day	100 €	Design with DWG
Social media links	2 days	200 €	Design with writers
i18n Theme	2 days	200 €	Design with translators
	25 days	2500 €

---

Beta Phase: improvements and preparation for Release Candidate

Task	Time estimation	Compensation	Collaboration
Setup of FreeCAD web group			Discussion with FPA and other teams
Design, layout and style improvements	5 days	500 €	Design with DWG
Content Management System	2 days	200 €	Design with writers
Code refactor	2 days	200 €
Cleanups and comments	1 day	100 €
Site documentation	1 day	100 €
Issue and PR templates	1 day	100 €
IE warning	1 day	100 €
Preparation for Release Candidate	2 days	200 €	Discussion with FPA
	15 days	1500 €

Edit of 12 June: fixed typo, removed misc and adjusted totals

Total Compensation for the Step 1 grant: 4000 €

---

Included in the above quote but not detailed:

• monthly meetings and notes
• detailed issues or discussion for on-boarding contributors
• dependencies updates, resolutions and bugs report to upstream
• report and discussion after each phase

Not included in the above quote and out of the scope of this first step:

• Tasks to be addressed in Step 2 or later steps (e.g. final content for the website, resolution of bugs during RC phase)
• Large re-architecture (e.g. change to dynamic stack) or big new features unlisted above (e.g. unified FreeCAD user account login system)
• Features deemed unfit at this stage, to be defined with interest groups, writers and translators

Timeline

The Alpha Phase is expected to last from June to September 2025.

The Bela Phase is expected to last from September to November 2025.

If this proves successful, a second FPA grant proposal in Q4 for Step 2 will be prepared.

Risks and mitigation

Time availability: due to personal or professional unforeseen circumstances, contributors may have to delay some tasks. The scheduling in two phases and the setup of an interest group may allow to revise the overall strategy, the definition and allocation of tasks among members.

Challenge in reaching a design consensus: due to divergence in opinions and experiences, contributors may not agree on particular choices or design. The setup of an interest group, consultation of other stakeholders, exploration of alternatives if not too time-consuming, emphasis on dialogue and benefits of reaching common ground may partially alleviate individual discrepancies.

About you

Coordination is assured by @marcuspollio as are most Step 1 tasks. Collaboration among existing involved and new contributors is most welcome. This includes above listed tasks, in which case the corresponding compensation will be awarded, or for others tasks as well. Design, content, comprehensive testing, code contributions and review are equally valued.

Pending questions

• Development environment: currently, the unified prototype is being developed in a public but personal repository. A migration is expected, also for coordination reasons. When is this migration preferred? After the approval of the grant, after the completion of all above tasks and just before the Release Candidate?

Footnotes

1. FreeCAD's websites improvements initiative - Step 1 : Homepage and blog migration on FreeCAD-Homepage repository. ↩

2. Temporary development repository for the new unified FreeCAD website on OP author repository. ↩

3. UX-Topics: FreeCAD's websites improvements initiative on FreeCAD's Discord channel. ↩

[hyarion]

I like the proposal and the work that you've done so far and I think the scope is good.
It could be argued that this should be split up into Alpha for Q2 and Beta stage for Q3 as separate grants, but I think it makes sense to keep them together in one grant as defined by @marcuspollio. This as some alpha and beta work might overlap in time without a clearly defined line to separate them, especially if more people gets involved in the project.

I do think that the time estimates per task are on the optimistic side (for example, I don't think the features page will be completed in just 1 day if you take discussions and revisions into account). but there's no deadline so the exact timing doesn't matter that much. I think the current compensation set for each task is good though (even if it takes longer time depending on discussions).

[Reqrefusion]

Great work as always. I don't know if there's any point in breaking it down into so many parts, but it could be functional somehow. Personally, my expectations from a website (being original, interesting, etc.) are different, and this expectation is not shared by many members of DWG. That's why I don't have anything to say. I hope that the development will accelerate with the grant.

[marcuspollio]

@hyarion @Reqrefusion Thanks for the feedback!

Yeah, I agree with the original aspect. Currently the prototype is a bit boring and lacks a personal/original touch.
That said, as it is mostly an "informational" website and not a web app or "experience" focused, I would keep the navigation and structure as KISS as possible and focus the effort on originality on the layout, content and style. Theses aspects can be gradually iterated and improved as more people get involved too. Does it make sense?

[chennes]

Thank you for your grant proposal: it is now under review for the Q2 2025 grant cycle. The technical review committee will present its analysis to the FPA in two weeks, at which point the FPA vote process will begin, concluding on or before 1 July 2025, at which point funding decisions will be announced. You are welcome to modify your proposal to accommodate feedback received from the community during that time.

[yorikvanhavre]

I liked the proposal and I liked much what you've been doing so far. This is going in the right direction. It is simple, it is well organized, it is gitable, it is modular, it is translatable, it is themable. Making this become "live" would be a great achievement.

[chennes]

Thank you again for your proposal. The FPA's discussions took longer than anticipated, so the final vote was delayed. That vote is open now, and I will update this issue with the results when they are available.

[Reqrefusion]

The FPA's vote on the Quarter 2 2025 grant proposals is complete, and this grant was selected for funding. Congratulations @marcuspollio

FPA is pleased to see someone as organized as you working in such a valuable field.

FPA wishes to be more in contact with those who receive grants. For this reason, it has authorized a member. Currently, I am the authorized member responsible for these grant relationships. I will try to stay in constant communication with you. You can specify your preferred communication channel via email or here if you wish. Until then, the official communication space we will use will be this issue.

It has nothing to do with you, but I think I should inform you. If you are missing for 90 days without providing any excuse, the grant will be removed from the FPA budget.