Skip to content

How-to Docs: Creating a new concept #370

Description

@junedev

We have the "spec" style documentation about what is in a concept once it is done but we don't have a document about how to approach creating a new concept from scratch.

Some notes on what could be mentioned:

  • Making sure the new concept fits the concept tree
    • work off an existing issue or open an issue to discuss with maintainers first before jumping in
    • think about where the concept will sit in the tree and what prerequisites can be assumed when writing the introduction content
  • Collect/read some resources on the concept if you are not yet super familiar with the concept
  • If not provided in the issue, think about the learning objectives of the concept and what is out-of-scope
  • If the topic is somewhat larger, think about the subsections it might have
  • The empty file is the biggest enemy, start by writing a very bad draft and iterate from there
  • Only writing the introduction.md version first and using it also as about.md can help to build up a syllabus more quickly, more advanced content can always be added to the about file later on.
  • Make sure to keep the introduction minimal

(I am not sure how to ensure that content is not duplicated between this document and the spec style document we already have. Some content would fit both document. We might need to think a bit more about how to draw the line/how they work together.)

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions