Question Box Template Example

Learn how to use the question box template in your API documentation

Table of Contents

Question Box Template

The Question Box template provides a standardized way to present questions throughout your documentation. This helps readers consider important aspects of the topic being discussed and encourages critical thinking.

Basic Usage

To include a basic question box with default styling:


{% include question_box.html 
  title="Questions to consider:" 
  questions=site.data.questions.protocol 
%}

This will produce:

Questions to consider:
  • What protocol is being used in the URL?
  • Is the communication secure (HTTPS) or insecure (HTTP)?
  • Is this protocol appropriate for the type of data being transmitted?
  • Are there any specific security considerations related to this protocol?
  • Does the API documentation specify which protocol should be used?
  • Are there any protocol-specific headers or parameters required?

Customizing Your Question Box

You can customize the appearance of your question box using the following parameters:

Custom Icon


{% include question_box.html 
  title="Security considerations:" 
  icon="fas fa-shield-alt"
  questions=site.data.questions.url_security 
%}

This will produce:

Security considerations:
  • Does the URL contain any sensitive information that should be removed?
  • Is HTTPS being used to protect the URL during transmission?
  • Could the URL be susceptible to path traversal attacks?
  • Are there any URL length limitations to consider?
  • Should any of the parameters be moved to the request body for security purposes?
  • Are there input validation measures for URL components?

Custom Color


{% include question_box.html 
  title="Design considerations:" 
  icon="fas fa-pencil-ruler"
  color="#2a7d8c"
  questions=site.data.questions.url_design 
%}

This will produce:

Design considerations:
  • Does the URL follow RESTful design principles?
  • Is the URL human-readable and intuitive?
  • Does the URL use plural nouns for collections?
  • How deep is the URL hierarchy, and is it appropriate?
  • Is versioning incorporated into the URL structure?
  • Does the URL avoid exposing implementation details?

Available Question Sets

The following question sets are available in site.data.questions:

  • protocol: Questions about URL protocols
  • domain: Questions about domain names
  • path: Questions about URL paths
  • query_parameters: Questions about query parameters
  • fragment: Questions about fragment identifiers
  • endpoints: Questions about API endpoints
  • resources: Questions about API resources
  • url_encoding: Questions about URL encoding
  • url_design: Questions about URL design
  • url_security: Questions about URL security

Adding Custom Questions

You can also provide questions directly in your include:


{% include question_box.html 
  title="Documentation checklist:"
  icon="fas fa-clipboard-check"
  color="#6a994e"
  questions=my_custom_questions
%}

Where my_custom_questions is defined in your front matter or a data file:

my_custom_questions:
  - "Is the documentation clear and concise?"
  - "Are all technical terms properly defined?"
  - "Does the documentation include examples?"
  - "Is the documentation up-to-date?"

Benefits of Using the Question Box Template

  1. Consistency: Ensures all question sections have the same look and feel
  2. Maintainability: Makes it easy to update questions across multiple pages
  3. Visual appeal: Draws attention to important considerations
  4. Flexibility: Allows customization while maintaining design standards
  5. Organization: Groups related questions together in a structured format

Best Practices

  • Keep questions concise and focused
  • Group related questions together
  • Use appropriate icons that relate to the question topics
  • Choose colors that complement your documentation design
  • Include 5-10 questions per box for optimal readability
Previous: REST APIs Key Concepts and Structure Next: Types of APIs - A Complete Overview
Start your learning journey!
Course Progress 0%
0 of 0 pages completed

Found value in the course?

Your support fuels my work!

Buy Me A Coffee