Writing your doc

The drafting process will differ depending on the Issue description. If an edit is required as opposed to a new entry, you will not be creating any new files. Rather, you’ll be making changes to existing files as needed. If you’re working on a code editor, multiple changes to multiple files may be a quicker process as opposed to using GitHub where you have to navigate to each file and edit them one by one. Making changes solely through GitHub will require additional assistance from maintainers with tests. Also consider that installing additional software will take some time to properly set up at first. Whatever method you feel most comfortable with should be alright.

Begin planning your write-up

You can look at various related topic, concept, or term entries. For example, if you’re working on a term entry, it would be helpful to look at other terms that relate to the concept. It’s also a good idea to search through other documentation sites like W3Schools to figure out what to include in your entry. Please remember though to use your own words when writing.

Find the correct file path

Generally, the issue description will include the correct file path. In the case that you are not given the path, you can successfully find the correct path after understanding the content structure of Docs.

The content folder is located inside the root directory or folder of the Docs project. This is where all the written content that is displayed live on Docs is located:

Three types of entries live in this folder: topic, concept, and term entries. When you first look into the content folder, you’ll find all the topic folders. Topics can be found at the highest level and cover programming languages and various subjects like Artificial Intelligence. When you look into each topic folder, you’ll see the topic file and a concepts folder. Concepts break down each topic into its fundamental points and describe some abstract or tangible idea. Within each concept folder, you will find a concept file and may find a terms folder. Terms all relate to the given concept in a similar way. Many technical entries at this deepest level require using code blocks of a specific language to explain the term.

Add media or images

The media folder stores all image files that are displayed on Docs:

To add an image, the file size should be <1 MB in size which allows for quicker load time. You can add an image using the following markdown format:

![Image Name](https://raw.githubusercontent.com/Codecademy/docs/main/media/<file-name>.<file-extension>)

Here, the image name is wrapped in square brackets with an exclamation mark in the opening bracket. The link to the image is wrapped in parentheses and contains the name of the file that you added to the media folder.

Refer to entry templates and style guide

The documentation folder is also located inside the root directory of Docs. It houses templates which are a great starting point. These templates should be referenced based on the type of entry that’s requested whether it be a topic, concept, or term entry.

Within this folder, you’ll also find a style guide markdown file that goes over the Docs content style in detail. For example, using any type of pronoun like you or we to address the reader is restricted. We do not expect your content to be perfect as maintainers will help standardize the writing. Rather, it’s important to accept feedback wherever necessary and be mindful of the Docs style. Sticking to this guide will help you get a better understanding as to what maintainers look for when reviewing content. For a higher level overview of general standards prior to writing an entry, you can look through the content standards markdown.

Metadata

You’ll notice that within each file, a metadata section rests at the top of the file. There are some helpful comments trailing on each key’s line. These comments should be removed after drafting up your entry:

There are a few fields in the metadata that you need to include:

• Title: This is the text that will display at the top of the entry when it renders on the Codecademy site.
• Description: If you’re writing a term entry, this text should start with a verb. For all types of entries, this text should be 2-3 sentences maximum.
• Subjects: These are fixed based on the available subjects on Codecademy. For an extensive list of subjects, there is a file within the documentation folder named subjects.md that you should reference.
• Tags: For an extensive list of tags, there is a file within the documentation folder named tags.md. If there is a tag that is relevant to the entry and does not exist in the tags markdown, make sure to add the tag to the markdown.
• CatalogContent: Appears at the bottom of the entry and links to certain courses or paths available on Codecademy. Examples are available in the catalog-content.md file.

Revise your entry

Revising your entry prior to submission is a good way to speed up the review process. Having someone else read over your entry to lend an alternative perspective can help clarify any errors you may have missed when self-revising. We also highly recommend running your entry through grammarly even if English is your first language.

For testing out code examples, you can choose from many options available online. If you’re working on a term and already have a relative term up with a codebyte (runnable code block), you can replace the code with one you’re testing out. Some Codecademy tools you can utilize to test out some piece of code include Codecademy’s codebyte editor or Workspaces.

Alternatively, online compilers are a quick search away (ensure the site is secure by looking to see if the URL starts with “https”). Every language also has some type of sandbox available that is accessed through the command line or terminal. For example, Node.js has a sandbox which allows you to write in JavaScript. If the code you need to test out is more specialized, first search for existing documentation on how to set up your environment. However, if you get stuck, reach out to a maintainer and we’ll do our best to help you out or direct you to a helpful source.