From 6e4a39a6347321c7562f4717fcdb0d9b079f48a2 Mon Sep 17 00:00:00 2001 From: Daria Vladykina Date: Thu, 9 Mar 2023 11:43:00 +0100 Subject: [PATCH] Update README.md Fix typos --- templates/README.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/templates/README.md b/templates/README.md index e7d1907c9..c7e59d55a 100644 --- a/templates/README.md +++ b/templates/README.md @@ -11,7 +11,7 @@ These templates act as a blueprint for topic-oriented writing in DocBook. # Using these templates The templates in this directory are already contained in a directory structure that matches the -one of a real project. See the naming and directory convenions outlined below. +one of a real project. See the naming and directory conventions outlined below. If you are starting a topic-based authoring project from scratch, you can just copy this directory tree and start adjusting file names (DC file, assembly and topics) and root IDs as outlined below. @@ -20,7 +20,7 @@ Once you have named the files accordingly, integrate them into the assembly file Write the new content and adapt the IDs. -In a final step, add suitable meta data information to your assembly file. Stick to the +In a final step, add suitable metadata information to your assembly file. Stick to the conventions outlined below. @@ -31,9 +31,9 @@ We provide five different types of information units: * `assembly.asm.xml`: Assembly (builds the actual "article" from the components listed below) * `task.xml`: Task (how to?) * `concept.xml`: Concept (what is?) -* `reference.xml`: Reference (e.g. list of options, table with config files, default settings) +* `reference.xml`: Reference (e.g., list of options, table with config files, default settings) * `glue.xml`: Combines texts or structures that do not fit into any of the other categories. -Typicalglue topics include the intro section to your article, the "For more information" and the +Typical glue topics include the intro section to your article, the "For more information" and the "What's next" sections. Also use glue topics to add an additional layer of navigation to your article. This is outlined in the `glue.xml` example file. @@ -68,7 +68,7 @@ The DC file name must match the assembly file's root ID. ### File naming conventions -Always start with the overarching topic. If necessary, add a suptopic (append with `_`): +Always start with the overarching topic. If necessary, add a subtopic (append with `_`): ``` autoyast systemd @@ -104,7 +104,7 @@ Working with assemblies, you need to distinguish between two types of IDs: * `external IDs`: These are visible to the world. * `internal IDs`: Internal references inside the assembly used to organize the content snippets. -External IDs are build in a similar fashion as file names. As with file names, never include the +External IDs are built in a similar fashion as file names. As with file names, never include the topic type in your ID. ``` @@ -117,7 +117,7 @@ To build an internal ID, prefix the external ID with an underscore (`_`). ### Image naming conventions Make sure your images can be associated with the topic they belong to. Use a similar naming scheme -for images than you use for topic files. +for images that you use for topic files. ``` @@ -130,10 +130,10 @@ We maintain a changelog for each article. Add a version to the changelog wheneve artificially bloat the changelog by entering every single commit. Also, provide concise and meaningful version information that the reader benefits from. -## Meta data +## Metadata -Once your article is done, add a meta data layer to the assembly file. Check the `assembly.asm.xml` -file for XML synthax and possible values. The following meta data types are currently supported: +Once your article is done, add a metadata layer to the assembly file. Check the `assembly.asm.xml` +file for XML synthax and possible values. The following metadata types are currently supported: * Internal * SEO @@ -143,21 +143,21 @@ file for XML synthax and possible values. The following meta data types are curr ### Internal -1. Add maintainer info (e-mail address) to the assembly and all the topic files. Use this information to contact the original author, in case you want to re-use a piece and would like to start a conversation on changing the file. +1. Add maintainer info (e-mail address) to the assembly and all the topic files. Use this information to contact the original author, in case you want to reuse a piece and would like to start a conversation on changing the file. 1. Determine whether the article needs to be translated and add a list of languages. -1. If you have re-used content from existing legacy (non-modular) docs, adjust the pointer in the +1. If you have reused the content from existing legacy (non-modular) docs, adjust the pointer in the XML comments of your file. By adding a similar pointer to the legacy doc piece, you make sure that you keep both docs in sync. This is done using a plain XML comment. ### SEO -Add some search engine related information to your file: +Add some search engine-related information to your file: 1. `title`- 29-55 characters 1. `description` - max. 150 characters ### Search -Add as much search-related data to your article as possible. Chose the appropriate tags: +Add as much search-related data to your article as possible. Choose the appropriate tags: * `productname` * `productversion` * `architecture` @@ -165,9 +165,9 @@ Add as much search-related data to your article as possible. Chose the appropria ### Publishing info -Provide the reader with some guidance on the articles "age" (`updated`). +Provide the reader with some guidance on the article's "age" (`updated`). ### Social media -Provide an ultra-short (55 chars) description (`social-descr`) of your doc to make sure your it +Provide an ultrashort (55 chars) description (`social-descr`) of your doc to make sure it gets properly shared via Facebook and Twitter.