Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
Fix typos
  • Loading branch information
dariavladykina authored Mar 9, 2023
1 parent 1b3ebe8 commit 6e4a39a
Showing 1 changed file with 16 additions and 16 deletions.
32 changes: 16 additions & 16 deletions templates/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.


Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

```
Expand All @@ -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.


```
Expand All @@ -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
Expand All @@ -143,31 +143,31 @@ 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`
* `category`

### 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.

0 comments on commit 6e4a39a

Please sign in to comment.