Conceptual content helps people understand a feature or topic by providing a clear, high-level overview, explanation of how the feature or topic can help them on their journey, and context like use cases or examples.
We create concepts articles and conceptual sections within other articles. Most major products, features, or subjects have their own concepts article.
Deciding between an article or a section
How-tos or tutorials can have 1-2 brief introductory sentences before the steps. If more explanation beyond a couple of sentences is needed, that’s when we should consider whether it merits a spot in a concepts article.
However, we should be selective. Not every concept or “About X” section needs its own article. Generally this comes down to how much information will be useful to the user that we need to include.
How to write conceptual content
For the conceptual content template, see 템플릿.
- Describe in plain language what the feature, product, or topic is.
- Describe its purpose and why it’s useful to the reader.
- Share use cases or examples.
Titles for conceptual content
Short titles for articles should be one word or a noun phrase. If the articles appear under Concepts in the sidebar avoid using "About", unless the article appears under a heading of the same name. Ex: "Coding agent" and "About coding agent".
Headers of conceptual sections in articles start with "About [subject]”.
- Use a noun to describe the subject.
- Use: "About code scanning"
- Avoid: "About scanning your code for vulnerabilities"
Examples of conceptual content
- Conceptual articles
- Conceptual sections within other articles
- "About security policies" in Adding a security policy to your repository(리포지토리에 보안 정책 추가)
- "About maintenance mode" in 유지 관리 모드 사용 설정 및 예약