Update: (root) README #2010
Update: (root) README #2010
Conversation
There was a problem hiding this comment.
While a quick glance at the resulting README looks pleasant, I am quite concerned about the form of this PR.
Take for example the commit message:
Update: (root) README
That's it. I would be much more convinced of these changes if the commit message followed the guidance in https://github.blog/2022-06-30-write-better-commits-build-better-projects/ to improve it, in particular with a strong focus on this part:
| What you’re doing | Why you’re doing it | |
|---|---|---|
| High-level (strategic) | Intent (what does this accomplish?) | Context (why does the code do what it does now?) |
| Low-level (tactical) | Implementation (what did you do to accomplish your goal?) | Justification (why is this change being made?) |
And then there are many, many, many changes, all squashed into a single commit, making it very, very easy to miss anything undesired.
Simple example: the ```console construct is supposed to show a shell session, including prompts. Yet all of those $ prompts are removed. Hrmpf.
Other example, some of the more in-depth information is simply removed. Maybe an improvable idea?
Instead, a large set of changes should be structured into individual commits, each with a commit message that makes a good case for the introduced changes.
One such commit could be to add a table of contents. That should probably even be one of the first commits of this PR, if not the first.
Then, if you still insist on removing those $ prompts from the shell sessions, that would need to be its own commit (if only to make it easier to drop that part and not having to drop all other changes at the same time).
Don't get me wrong, I like a lot what I am seeing in the result. It's just that the current form of the PR makes it really, really hard to improve it. And improving it still needs, from my perspective at least.
|
|
||
| > [!NOTE] |
There was a problem hiding this comment.
I am pretty concerned about removing an important visual marker like this.
I am not saying that you have to reinstate it if the new look gets too broken up by it, but I am saying that simply stating that the site was rewritten is a tad too little to convince me that all of these broad changes that are smooshed into a single commit are actually good.
|
|
||
| Supported browsers include `firefox`, `chromium`, `webkit`, `chrome`. You can also simply download all of them using `npx playwright install` but please first note that they all weigh >100MB, so you might want to refrain from doing that. Side note: In GitHub Actions' hosted runners, Chrome comes pre-installed, and you might be able to use your own Chrome installation, too, if you have one. |
There was a problem hiding this comment.
Hmm. I'm not a fan of dropping this important information on the floor.
|
I'd just like to state that I stopped at only two comments because I anticipate that it will be much easier to review and improve this PR once the changes are broken up into a proper set of commits, not because there is nothing more to comment on. |
|
Hey @dscho , I understand your concerns, I'll redo this PR in the manner you have suggested. |
@RafaelJohn9 thank you. BTW if I were you, I'd use the technique described in https://git-scm.com/docs/git-rebase#_splitting_commits to avoid redoing the PR but instead simply splitting all the existing changes into appropriate commits. I find that |
|
thanks 👍 , everyday is a new learning day 😅 |
Totally! |
Move badges below the title to improve visual hierarchy. Reword the opening paragraph to make the purpose of the site clearer for first-time visitors.
Replace initial local development note with a comprehensive Table of Contents Organize sections for easy navigation: Getting Started, Local Development, Testing, Content Updates, Contributing, etc.
Introduce "Cloning the Repository" guide Recommend using scalar for efficient sparse cloning
Make commands easier to copy and paste without errors
Add "Alternative: Manual Sparse Clone" section for users without scalar Provide clean, prompt-free shell commands to improve copy-pasting Enhance usability of the cloning instructions
Reformat note for better readability and emphasis Clarify instructions for users with a full clone to focus on subsets Improve tone and consistency in documentation style
Provide brief explanations for each relevant directory Improve clarity for developers navigating the project layout
…uctions Add a new "Local Development" section with subsections for prerequisites and serving the site Specify required tools: Hugo (extended v0.128.0+), Node.js, and Windows WSL recommendation Improve instructions for verifying Hugo version and serving the site locally Clarify note about pre-rendered directories and GitHub workflows
Reword instructions to use Hugo’s built-in server. Explain the need to disable “ugly URLs” for compatibility with GitHub Pages Add a clear note defining “ugly URLs” and why serve-public.js emulates GitHub Pages behavior
…atting Introduce instructions to build the site with search enabled using Hugo and Pagefind Remove $ prompt symbols from shell commands to improve copy-pasting experience Improve clarity and usability of local testing documentation
Rephrase to highlight using Pagefind’s built-in server. Remove $ from shell commands for easier copy-pasting Add a clear note about slower performance and disabled live reload when using Pagefind
Rewrite introduction to describe Playwright test suite and location clearly Add “Running Tests” subsection with step-by-step instructions Remove $ prompt symbols from shell commands to simplify copy-pasting Improve overall structure and readability of the testing setup documentation
Reorganize the Playwright testing section to improve clarity and usability. Adds headings, formatting, and notes on browser download sizes. Also explains how to run tests against local changes and filter tests with regex.
Add clear headings under 'Content Updates' for installing Ruby dependencies and generating manual pages. Reorganize steps to separate local and remote build instructions, and format code blocks consistently for better readability.
…teps Structured manual page instructions into local and GitHub-based workflows. Added steps for building localized manual pages using git-html-l10n. Improved formatting and clarity for version-specific builds and prerequisites.
Renamed "Update the ProGit book" section to "ProGit Book" for clarity. Added step-by-step formatting for prerequisites and script usage. Clarified how to fetch and update book content from local repositories. Updated download data instructions for improved readability.
Reorganized steps into clearly numbered list. Added cloning instructions and clarified directory structure. Documented alternative GitHub-based update method using API tokens. Explained how to build the book for all available languages.
Encouraged contributions with a more welcoming tone. Recommended using scalar and sparse-checkout for efficiency. Added guidance on making pull requests and opening issues for features.
Added a new section with step-by-step guidance on contributing GUI client entries. Clarified metadata fields required in the .md file. Provided image naming and formatting requirements. Ensured platform and ordering fields are clearly explained.
Promoted "Hugo", "Pagefind", "Lychee", and "Playwright" to top-level headings. Reorganized and standardized the formatting of resource links. Improved clarity and readability by aligning structure with other sections.
Promoted license section to a top-level heading. Consolidated license descriptions for source code and graphical assets. Enhanced readability and link presentation.
RafaelJohn9
force-pushed
the
update/README
branch
from
39c6486 to
863f29f
Compare
Changes
Context
I’ve updated the
README.mdto improve the overall clarity and structure. The goal of these changes is to make it easier for new contributors and developers to understand how to set up the project locally, run tests, and begin contributing. I’ve tried to keep the original intent and flow intact, while rewording or reorganizing certain sections for better readability and guidance.Thank you for your time and for reviewing the changes!