Yoast / Yoast/developer

Add documentation for Free, Premium, and other add-on assessments to developer.yoast.com

Open
#226 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
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:

Example of how this will look:

SEO

Readability

Inclusive Language


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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.