Add documentation for Free, Premium, and other add-on assessments to developer.yoast.com
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 15
- Forks
- 23
- PR merge metrics
- No merged PRs in 30d
Description
Please give us a description of the issue
- I've read and understood the contribution guidelines.
- I've searched for any related issues and avoided creating a duplicate issue.
This task was created as part of this task: https://github.com/Yoast/non-dev-tasks/issues/39
See report in first comment to this task for context.
All assessments:
In developer/docs/features/analysis create a folder called assessments.
overview.md
Within this folder create one overview.md with some general information and links to all assessment specific docs. Could also contain a legend/explanation of the card system (see below).
This should have a docusaurus header like so:
---
id: overview
title: "Assessments: Overview"
sidebar_label: Overview
description: This documentation provides a list of all our assessments.
---
This overview should contain a list of all (Free and Premium) SEO, Readability and Inclusive Language assessments by their type/source. And all assessments should link to the assessment specific page (see below). Note: there are separate tasks to add documentation related to add-ons and Shopify:
- Add documentation for e-commerce specific assessments and scoring criteria to developer.yoast.com
- Add documentation for add-on specific assessments to developer.yoast.com
Example of how this will look:
SEO
Readability
Inclusive Language
- Age
- Appearance
- Culture
- ...
Assessment specific pages
Within the assessments folder, create a folder for each assessment type/source. NOTE: use snake casing as this appears to be the convention withing developer.yoast.com. For example inclusive-language.
In each respective folder, create an .md file for each assessment. (Again, use snake casing: keyphrase-in-introduction.md)
Each file should have a Docusaurus header at the top. For example:
---
id: KeyphraseLengthAssessment
title: "Assessments: KeyphraseLengthAssessment"
sidebar_label: Keyphrase Length
description: This documentation provides an overview of the Keyphrase Length Assessment.
---
Docusaurus will interpret this header.
Each file could contain a card with some essential information in a structural format. This could also house some information from SCORING SEO.md, SCORING READABILITY.md and SCORING INCLUSIVE LANGUAGE.md that is not in the second card below. For example:
| Keyphrase length | |
|---|---|
| Name In Code | KeyphraseLengthAssessment |
| Title URL: | https://yoa.st/33i (link placement is in bold in the feedback strings) |
| Call to action URL | https://yoa.st/33j (link placement is in bold in the feedback strings) |
| What it does | Checks whether the number of ( content ) words in the keyphrase is within the recommended limit. For languages with function word support only content words are considered. For languages without function word support all words are considered. |
| Uses synonyms | ❌ |
| When it applies | Always. |
| Addon/Premium | ❌ <whether it is part of an addon or premium> |
| Languages | Agnostic |
| Cornerstone | ❌ <whether it is changed by cornerstone toggle> |
| Uses highlighting | ❌ |
| Uses morphology in premium | ❌ |
| Other | <Any additional info that might be relevant.> |
Below this card, create a card for scoring. This can be copied from SCORING SEO.md, SCORING READABILITY.md and SCORING INCLUSIVE LANGUAGE.md. For example
| Bullet | Score | Criterion | Feedback |
|---|---|---|---|
| Red | -999 | No focus keyword set | Keyphrase length: No focus keyphrase was set for this page. Set a focus keyphrase in order to calculate your SEO score. |
| Red | 3 | Keyphrase length > 8 words (> 9 for languages without function words support) | Keyphrase length: The keyphrase contains x (content) words. That's way more than the recommended maximum of 4 (content) words. Make it shorter! |
| Orange | 6 | Keyphrase length between 5-8 words (7-9 for languages without function words support) | Keyphrase length: The keyphrase contains x (content) words. That's more than the recommended maximum of 4 (content) words. Make it shorter! |
| Green | 9 | Keyphrase length between 1-4 words (1-6 or languages without function words support) | Keyphrase length: Good job! |
Below this card there is space for free text/context/screenshots/desired behaviour.
Do not remove these cards from the yoastseo package. Also do not move any other documentation from the yoastseo package. There is a separate task to deal with that: https://github.com/Yoast/lingo-other-tasks/issues/211
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by inspecting the existing structure under docs/features/analysis and the Docusaurus documentation conventions. Use the linked SCORING SEO.md, SCORING READABILITY.md, and SCORING INCLUSIVE LANGUAGE.md files as source material; done means adding assessments/overview.md plus the requested assessment-specific folders and pages without removing or moving yoastseo documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100