Improve docs #12543
Draft
Improve docs #12543
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
SiAdcock
commented
Oct 11, 2024
|
|
||
| > If you use nvm, you might find | ||
| > [this gist](https://gist.github.com/sndrs/5940e9e8a3f506b287233ed65365befb) helpful. | ||
| We recommend using [fnm](https://github.com/Schniz/fnm) to help manage multiple versions of Node.js on on machine. |
There was a problem hiding this comment.
Let's not recommend asdf or nvm
SiAdcock
commented
Oct 11, 2024
| @@ -39,7 +27,6 @@ $ make dev | |||
| ``` | |||
|
|
|||
| `make dev` will start the development server on port 3030: [http://localhost:3030](http://localhost:3030). | |||
| `make build && make start` will start the production server on port 9000: [http://localhost:9000](http://localhost:9000). | |||
There was a problem hiding this comment.
We very rarely need to do this
SiAdcock
commented
Oct 11, 2024
| | `DISABLE_LOGGING_AND_METRICS` | Boolean. Toggle for enabling Log4js | | ||
|
|
||
| Most of these variables are set by our make scripts and you don't need to worry about setting them. | ||
|
|
There was a problem hiding this comment.
Moved to detailed setup
SiAdcock
commented
Oct 11, 2024
| @@ -84,9 +59,6 @@ If you're new to JavaScript projects, if you're trying to integrate with other a | |||
|
|
|||
| [Source](https://theguardian.design) is the Guardian's design system. For detailed and up-to-date information on how to use it, see the [Source guide](https://github.com/guardian/csnx/blob/main/docs/source/README.md). | |||
|
|
|||
| For a high-level overview of some of the key ideas behind the design of the Dotcom website, see [design.theguardian.com](https://design.theguardian.com/). | |||
| This resource was made in 2018 and is not maintained so it <strong>should not be taken as authoritative</strong> on details, but most of it still applies and it gives a very quick and visual overview. It also provides an explanation of some journalism- or Guardian-specific terms that you might see in the codebase, like 'kicker' and 'standfirst'. | |||
|
|
|||
There was a problem hiding this comment.
This documentation is stale and will never be updated
SiAdcock
commented
Oct 11, 2024
|
|
||
| After completing this setup guide, we would greatly appreciate it if you could complete our [dotcom-rendering setup | ||
| questionnaire](https://docs.google.com/forms/d/e/1FAIpQLSdwFc05qejwW_Gtl3pyW4N22KqmY5zXoDKAUAjrkOwb2uXNcQ/viewform?vc=0&c=0&w=1). It should only take 3 minutes and will help us improve this documentation and the setup process in the future. Thank you! 🙏 | ||
|
|
There was a problem hiding this comment.
Nobody has completed this form in over 4 years
SiAdcock
commented
Oct 11, 2024
|
|
||
| - `pnpm prettier:check` → Checks for prettier issues | ||
| - `pnpm prettier:write` → Checks and fixes prettier issues | ||
|
|
There was a problem hiding this comment.
This is just the way DCR works. Deal.
SiAdcock
commented
Oct 11, 2024
| If you prefer not to use an editor like VSCode then you can use the following commands to manage formatting and (try to fix) linting errors: | ||
|
|
||
| - `make fix` → Checks and fixes prettier and linting issues | ||
|
|
There was a problem hiding this comment.
This is mentioned elsewhere
|
Size Change: 0 B Total Size: 898 kB ℹ️ View Unchanged
|
SiAdcock
commented
Oct 11, 2024
|
|
||
| <a href="https://www.chromaticqa.com/"><img src="https://cdn-images-1.medium.com/letterbox/147/36/50/50/1*oHHjTjInDOBxIuYHDY2gFA.png?source=logoAvatar-d7276495b101---37816ec27d7a" width="120"/></a> | ||
|
|
||
| Thanks to [Chromatic](https://www.chromaticqa.com/) for providing the visual testing platform that helps us catch unexpected changes on time |
There was a problem hiding this comment.
Chromatic used to offer us a free service if we called them out in our README. Since we now pay Chromatic handsomely, we no longer need to do this.
SiAdcock
commented
Oct 11, 2024
| <a className={cx({ [activeLink]: isActive }, link)}>Click Me</a> | ||
| ); | ||
| ``` | ||
|
|
There was a problem hiding this comment.
We don't use cx very much, certainly not enough to call it our code style
SiAdcock
commented
Oct 11, 2024
| @@ -32,5 +32,3 @@ In DCR we support these conventions using [enhance-images.ts](/dotcom-rendering/ | |||
| ## How remove these enhancement functions | |||
|
|
|||
| The construction of these functions has been done with the goal of removing them in mind. Where changes to elements have been needed they have been done in such a way as to be generic. For example, the special image titles used in photo essays are available for all images, on all article types. By doing this we create a design language that is more flexible so that if we later improve Composer to support, say, adding drop caps to any paragraph, or adding a title string to an image, then this will just work. | |||
|
|
|||
| For more information on how and why we'd like to improve cleaners see: https://docs.google.com/document/d/1ESuP7jEOEdbqbJ3mwuBXJxt6wXuGv9_klP3e2JXfSQY/edit | |||
There was a problem hiding this comment.
Doc no longer exists
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What does this change?
Why?
Screenshots