Skip to content

Commit

Permalink
Enhancements to the doc contributor guide for adding abstracts and re…
Browse files Browse the repository at this point in the history
…direction to diataxis styled topics

Added clarification about  the abstract/preamble.

Edits

Added native to doc categories

Removed native entry. This overlaps with another PR
  • Loading branch information
michelle-purcell committed Feb 15, 2023
1 parent 2f018c3 commit 3689bdd
Showing 1 changed file with 14 additions and 2 deletions.
16 changes: 14 additions & 2 deletions docs/src/main/asciidoc/doc-contribute-docs-howto.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,18 @@ include::_attributes.adoc[] <3>
<2> For information about how to create a good title for each content type, see xref:{doc-guides}/doc-reference.adoc#titles-and-headings[Titles and headings] on the "Quarkus style and content guidelines" page.
<3> The `_attributes.adoc` include is required to ensure that attributes get resolved, the table of contents is generated, and content renders in the website portal.
<4> Set at least one category to ensure that the content is findable on the link:https://quarkus.io/guides/[Quarkus documentation home page]. For a list of Quarkus categories, see xref:{doc-guides}/doc-reference.adoc#document-attributes-and-variables[Document attributes and variables] on the "Quarkus style and content guidelines" page.
+
[IMPORTANT]
====
Ensure there are no line breaks in the header section until after `:categories:` line.
====
+
. Add an abstract to describe the purpose of the guide.

This comment has been minimized.

Copy link
@sheilamjones

sheilamjones Feb 15, 2023

Contributor

Thanks @michelle-purcell. Looks very good to me and good to have this info also included here if we are no longer using the ":summary: " attribute.
Can we also remove/update the reference to the ":summary: " attribute in the "Other common attributes" section of the style and content guidelines (https://quarkus.io/version/main/guides/doc-reference#abstracts-preamble) to state that it is no longer being used for new docs and to point instead to the Abstract (preamble) paragraph?

[IMPORTANT]
====
The first sentence of the abstract must explain the value and some benefit of the content in less than 27 words because this automatically displays on the link:https://quarkus.io/guides/[Quarkus guides homepage].
There must also be a line break before and after the abstract.
====

For more information about the minimum header requirements, see xref:{doc-guides}/doc-reference.adoc#document-structure[Document structure] on the "Quarkus style and content guidelines" page.

Expand All @@ -75,8 +87,8 @@ newUrl: /guides/<new_asciidoc_filename> // <2>
---
+
Where:
<1> Is the name of the original AsciiDoc source file that you are retiring.
<2> Is the name of the AsciiDoc source file that you want to redirect to.
<1> Is the name of the original AsciiDoc source file that you are retiring, without the `.adoc` file extension.
<2> Is the name of the AsciiDoc source file that you want to redirect to, without the `.adoc` file extension.

.Example

Expand Down

0 comments on commit 3689bdd

Please sign in to comment.