[[templates]]
=== Topic templates

[role="summary"]
Templates for writing task and concept topics.


[[template-task]]
==== Template for task topics

We have separate templates for topics that cover tasks, and topics that cover
concepts. Here is the template for task topics, including the instructions (this
is file _templates/task-topic.txt_ in the project Git repository):

----
// This template is for a topic that covers how to perform a task.
//
// To use this template:
// - Copy it to your source directory with a new name, such as
//   "block-creating.txt". [The project coordinators may already have done
//   that for you.]
// - Follow the instructions that are contained in lines starting with //
//   throughout this file.
// - Replace placeholder text with your content.
// - Before you submit your topic, remove all the lines in the file that
//   start with // -- these are comments that do not belong in the topic. Also
//   remove any blank lines that are before the ID line.
// - Then, if there are sections that do not apply to your topic (for example,
//   Prerequisites might not), put // before the ==== on that line and leave
//   those lines in the topic file. So it would look like:
//==== Prerequisite knowledge


// The first thing in the file is an ID: replace the text in the brackets below
// so that it matches the name of the file (without the .txt extension; for
// example, [[block-create]] if the file name is block-create.txt.
[[noun-verb]]
// The topic title goes on the next line. Use "Title Case" for topic titles.
// Titles for task topics should be in the format "Verbing a Noun".
=== Verbing a Noun

// The next few lines are a summary of what the topic covers. Should start with
// "How to [verb]".
[role=summary]
How to verb a noun. No more than 140 characters. Wrap text at 80 characters if
it goes over.

// The next thing that is needed is an entry for the index:
// - Replace the text in (((Nouns,verbing))) with an appropriate index entry,
//   such as (((Blocks,creating))). You can add additional index entries if
//   appropriate.
// - Refer to the Guidelines if you have questions.
// - Also remove the // before the ((( so that this becomes an index entry
//   and not a comment.
//(((Nouns,verbing)))


==== Goal

// Describe the goal of this task here. This should be the goal for the reader,
// so describe the end result, like "Create an About page". It should relate to
// the Scenario and be specific rather than generic.

Remove this placeholder text.


==== Prerequisite knowledge

// This section should mostly link to topic and concept tasks within
// the guide that someone would need to understand before trying this task.
// Some of the entries could be background knowledge that is needed that is
// not covered in the guide.
//
// Some ideas (remove the // to make these not comments):
//* <<cross-reference-one>>
//* <<cross-reference-two>>
//* How to upload files from your local server to your web server.

Remove this placeholder text.


==== Site prerequisites

// The items below are an example of what might go here for a task where
// a "most recent image" view is created. They describe things that must be
// present on the site (configuration, content, etc.) in order to perform
// this task.
//
// Some ideas (remove the // to make these not comments):
//* A content type is defined with an Image field. See <<cross-reference-one>>.
//* At least one published content item of this type exists. See
//  <<cross-reference-two>>.

Remove this placeholder text.


==== Steps

// This is where you describe the actual steps needed to perform this task.
// Remember to use the scenario and be specific, not generic.

. Text of step one goes here. The subsequent lines of this step need
  to be indented by two spaces.

  And it could be a couple of paragraphs.
+
If you have a multiple-paragraph step, separate the paragraphs by + signs.

. Text of step two goes here.

. Text of step 3.

Notes:

* If your task involves filling out a form, include a screen shot.
* Also include a table of fields and values to fill in. See example below.
* The last step should be something that shows them the task has been
  completed. Include a screen shot.

Sample table of fields and values:

[width="100%",frame="topbot",options="header"]
|================================
|Field name |Explanation |Example value
|Menu link title |Title to be displayed in the menu |Opening hours
|Second field |Second explanation |Second example value
|================================

==== Expand your understanding

// In this section, you can make cross-references to other task topics in this
// book that are related. You can also make suggestions for tasks that someone
// who just learned this task might be able to do that are not in the book --
// try to think of tasks that would help someone solidify and broaden their
// skills and knowledge, especially other tasks related to the scenario.
//
// However, if a task is required in order to satisfy the Site Prerequisites
// of a later task, put it in Steps and not in this section.
//
// Some ideas (remove the // to make these not comments):
//* <<cross-reference-1>>
//* Brief description of another task not in the book.

Remove this placeholder text.


==== Related concepts

// In this section, add links to related concept topics, if any.

Remove this placeholder text.


==== Videos

// In this section, embed videos that exactly cover this topic. For videos
// that are related but do not exactly cover the topic, add links in the
// Additional resources section instead.
//
// Syntax to embed a video (remove the // to make it not a comment, and make
// sure the word "video" starts at the left margin of your text file):
//   video::https://www.youtube.com/embed/HymQsDOcT3E[title="Name of video"]

Remove this placeholder text.


==== Additional resources

// In this section, make a list of outside references: videos, Drupal.org
// documentation, etc. Make sure all links have link text showing the name
// of the article or page being linked to.

Remove this placeholder text.


*Attributions*

// Attributions information goes here.
----


[[template-concept]]
==== Template for concept topics

We have separate templates for topics that cover tasks, and topics that cover
concepts. Here is the template for concept topics, including the instructions
(this is file _templates/concept-topic.txt_ in the project Git repository):

----
// This template is for a topic that covers a concept.
//
// To use this template:
// - Copy it to your source directory with a new name, such as
//   "blocks-overview.txt". [The project coordinators may already have done
//   that for you.]
// - Follow the instructions that are contained in lines starting with //
//   throughout this file.
// - Replace placeholder text with your content.
// - Before you submit your topic, remove all the lines in the file that
//   start with // -- these are comments that do not belong in the topic. Also
//   remove any blank lines that are before the ID line.
// - Then, if there are sections that do not apply to your topic (for example,
//   Prerequisites might not), put // before the ==== on that line and leave
//   those lines in the topic file. So it would look like:
//==== Prerequisite knowledge


// The first thing in the file is an ID: replace the text in the brackets below
// so that it matches the name of the file (without the .txt extension; for
// example, [[block-overview]] if the file name is block-overview.txt.
[[id-goes-here]]
// The topic title goes on this line. Use "Title Case" for topic titles.
// Titles for Concept topics should start with "Concept: ".
=== Concept: ...

// The next few lines are a summary of what the topic covers. Should start with
// "Overview of".
[role=summary]
Overview of foo. No more than 140 characters. Wrap text at 80 characters if it
goes over.

// The next thing that is needed is an entry for the index:
// - Replace the text in (((indexentry))) with an appropriate index entry,
//   such as (((Blocks,overview))). You can add additional index entries if
//   appropriate.
// - Refer to the Guidelines if you have questions.
// - Also remove the // before the ((( so that this becomes an index entry
//   and not a comment.
//(((indexentry)))


==== Prerequisite knowledge

// This section should mostly link to topic and concept tasks within
// the guide that someone would need to understand before trying this task.
// Some of the entries could be background knowledge that is needed that is
// not covered in the guide.
//
// Some ideas (remove the // to make these not comments):
//* <<cross-reference-one>>
//* <<cross-reference-two>>
//* How to upload files from your local server to your web server.

Remove this placeholder text.


==== What is a ...?

// Describe your concept here. The title of this section should be
// What is a ...? or What are ...? (where the ... is the same as the topic
// title). If the topic title contains several things to describe, you can also
// have multiple of these "What is a ..." sections.
//
// If possible, relate this concept to the specific scenario of the guide,
// perhaps using "for example" language.

Remove this placeholder text.


==== Related topics

// In this section, make cross-references to related tasks and concepts that
// are covered in this book.
// Also remove the // so these lines are a list and not comments:
//* <<cross-reference-1>>
//* <<cross-reference-2>>

Remove this placeholder text.


==== Videos

// In this section, embed videos that exactly cover this topic. For videos
// that are related but do not exactly cover the topic, add links in the
// Additional resources section instead.
//
// Syntax to embed a video (remove the // to make it not a comment, and make
// sure the word "video" starts at the left margin of your text file):
//   video::https://www.youtube.com/embed/HymQsDOcT3E[title="Name of video"]

Remove this placeholder text.


==== Additional resources

// In this section, make a list of outside references: videos, Drupal.org
// documentation, etc. Make sure all links have link text showing the name
// of the article or page being linked to.


Remove this placeholder text.


*Attributions*

// Attributions information goes here.
----


*Attributions*

Written/edited by
https://www.drupal.org/u/jhodgdon[Jennifer Hodgdon] and
https://www.drupal.org/u/eojthebrave[Joe Shindelar].
