Website build improvements #11275
Website build improvements #11275
Conversation
Update dependencies to latest available versions to benefit from upstream improvements. Signed-off-by: Thomas Steenbergen <opensource@steenbe.nl>
Include the missing plugin generation command and add descriptions for each command for better clarity. Signed-off-by: Thomas Steenbergen <opensource@steenbe.nl>
Move the docs directory from the website directory back to the root of the repository. This change improves discoverability for users and aligns with standard best practices used by many open source projects. Signed-off-by: Thomas Steenbergen <opensource@steenbe.nl>
Signed-off-by: Thomas Steenbergen <opensource@steenbe.nl>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #11275 +/- ##
=========================================
Coverage 57.41% 57.41%
Complexity 1705 1705
=========================================
Files 346 346
Lines 12875 12875
Branches 1228 1228
=========================================
Hits 7392 7392
Misses 5005 5005
Partials 478 478
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
| "@mdx-js/react": "^3.0.0", | ||
| "clsx": "^2.0.0", | ||
| "prism-react-renderer": "^2.3.0", | ||
| "@easyops-cn/docusaurus-search-local": "^0.52.2", |
There was a problem hiding this comment.
Any idea why these updates were not covered by Renovate bot?
There was a problem hiding this comment.
I was wondering the same when making these updates but couldn't find any wrong within renovate.json.
There was a problem hiding this comment.
Could it be, that it's configured to not update lockfiles?
There was a problem hiding this comment.
As long as the version ranges defined in package.json still match the new version, Renovate will only update the package-lock.json. I think when using Renovate it's probably best to not use version ranges in the package.json at all because it makes it more obvious which versions are actually used.
Most updates to the package.json in this PR are just aligning with the versions already used in package-lock.json, for example, for clsx or prism-react-renderer. The React dependency was not upgraded by Renovate because #9565 was closed because Docusaurus was not compatible with React 19 back then.
|
|
||
| @OutputDirectory | ||
| val outputDirectory = project.layout.projectDirectory.file("website/docs/plugins").asFile | ||
| val outputDirectory = project.layout.projectDirectory.file("docs/plugins").asFile |
There was a problem hiding this comment.
I'm not sure about this change. There are website- / Docusaurus-specific files in docs, i.e. it's not generic Markdown files only. Also the argument about discoverability does not convince me, as users are not supposed to discover these from the repo, but to browse the website.
There was a problem hiding this comment.
I planning to remove any website- / Docusaurus-specific files from docs so we just left with the Markdown files. Have done lots of ORT onboarding sessions and trainings - and often get asked this 'where are the docs' question so this one has been high on my over to-do lists. Working on bigger rewrite of the docs have been playing with exporting the docs a user manual as a PDF/ePub and importable wiki.
There was a problem hiding this comment.
I planning to remove any website- / Docusaurus-specific files from docs so we just left with the Markdown files.
These files have a purpose, what will be the replacement?
The Markdown files also have Docusaurus specific content like frontmatter and Docusaurus specific extensions, what about those?
Have done lots of ORT onboarding sessions and trainings - and often get asked this 'where are the docs' question so this one has been high on my over to-do lists.
IMO the preferred way to consume the docs should be the website, not Markdown files rendered by GitHub. But if the issue is that people are not finding the docs on the website (despite the prominent link in the README), moving the folder will only promote reading them on GitHub. I would prefer to understand why people are not findings the docs and address that in a way that points them to the website.
playing with exporting the docs a user manual as a PDF/ePub and importable wiki
Is PDF export really something that anybody needs? And what is an importable wiki?
There was a problem hiding this comment.
These files have a purpose, what will be the replacement?
The Markdown files also have Docusaurus specific content like frontmatter and > Docusaurus specific extensions, what about those?
I wrote only about removing Docusaurus specific files, but as part of the ongoing ORT docs rewrite effort I have moved features relying on Docusaurus file comments to Docusaurus configuration files.
IMO the preferred way to consume the docs should be the website, not Markdown files rendered by GitHub.
Enterprise users usually do not operate on the latest versions of tools; they are often two to nine months behind. This delay is understandable as thorough testing prior to rolling out a new version is needed to ensure there are no tool regressions and that the new tool versions works well within their established processes and any extensions.
ORT is no different - enterprise users that are very active in the ORT community usually are less than month in the version of ORT they use don't confuse them as being what standard among all ORT users. Past experiences from issues have shown that many users are typically three to six months behind the latest release.
The ORT users within enterprises need docs matching the "validated version" of ORT (fork) used within their organization. The ORT website only contains docs for the latest version of ORT which is why I have had requests to have ORT user guide PDFs to be include in each release or support formats that enable ORT docs to be imported into wiki such as Confluence. Discussed as a solution that they could host the ORT website within their organization but that is usually not feasible due to internal operational/resources/security challenges so in the end most up having their users read ORT docs on their organization's GitHub/GitLab server.
Creation of package curations and configurations within large enterprises is typically done by teams in Asia in for instance India or Philipines. People in these "compliance/clearance" teams typically work based on documented procedure which are underpinned by ORT docs. By making ORT docs in the future available in other formats we enable easier remixing of its contents into for instance organization specific ORT training materials and ORT operating procedure guidelines.
There was a problem hiding this comment.
Enterprise users usually do not operate on the latest versions of tools; they are often two to nine months behind.
But that's a different problem statement than the original "docs discoverability" argument. To solve that problem, I'd prefer the website to have a version-dropdown (similar to Gradle's user manual) for user's to choose the rendered docs for a specific (past) release of ORT.
There was a problem hiding this comment.
Our weekly release schedule would result in a very long version-dropdown on the website which isn't very user‑friendly. We should separate docs from the site so they can be remixed and published in other formats — including downloadable ORT docs, which this article recommends for the Japanese market.
Excerpt:
In the U.S., the typical flow is that a prospect visits a website, books a demo on their own, or drops off and is followed up aggressively by sales. A conversation happens quickly, a proof of concept or trial begins, and the deal either closes or the buyer moves on to a competitor. The cycle is fast and transactional. Buyers are comfortable testing tools, replacing them, and switching vendors if something does not work.
In Japan, the process is slower and more deliberate. A company will usually download product materials first.
I heard the same from Japanese and Korean companies at Open Source Summit Japan (I was in Tokyo last December for the Open Source Summit Japan / Open Compliance Summit) - they, along with Germany, care about open source compliance done properly. To attract users and contributors from those markets, we need to support their preferred evaluation flow by offering downloadable documentation.
There was a problem hiding this comment.
I have the feeling that this discussion is too broad for a PR review, I would suggest to put it on the agenda of one of the recurring meetings to get an alignment on the goals first before talking about technical details.
| - pattern: "docs/**" | ||
| reason: "DOCUMENTATION_OF" | ||
| comment: >- | ||
| This directory contains project website with examples using licenses that do not apply to the OSS Review Toolkit. |
There was a problem hiding this comment.
The "examples [...] that do not apply to the OSS Review Toolkit" part sounds a bit odd to me, as if we were giving examples that are not workable.
Maybe better something like: "This directory contains documentation that is not distributed as part ORT releases."
4 participants
See individual commits for details.