jonashub/team-docs
1
0
Fork 0
forked from docs/team-docs
Code Pull requests Activity

Rewritten with style guide and conventions

Browse source
This commit is contained in:
hank L 2023-04-21 08:46:27 +00:00
commit cdd8052749
1 changed files with 11 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

24
modules/ROOT/pages/contributing-docs/index.adoc
View file

@ -1,4 +1,4 @@
= Write contributions to Docs
Update design-ux-contribution.adoc= Write contributions to Docs
Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
:revnumber: F36 and newer
:revdate: 2023-04-21
@ -12,19 +12,19 @@ ____
There are many different ways to contribute to Fedora documentation. Some of them are designed to enable contributions without technical knowledge about Web Content Management Systems and about how to store and manage your contribution. The tool takes over all these issues for you. It enables authors to concentrate on the topic at hand.
Please check us out. If you come across a documentation page that contains an error or inaccuracy, use one of the casual contribution tools described below to improve the page. You can't break anything, only improve it! If you have any questions, please do not hesitate to contact the Docs team.
Please check us out. If you come across a documentation page that contains an error or inaccuracy, use one of the casual contribution tools described below to improve the page. If you have any questions, please do not hesitate to contact the Docs team.
Other tools are designed to provide a powerful working environment for accomplished authors. They enable efficient work even on large complex interrelated text collections. These tools are aimed at experienced authors.
Local authoring tools are designed to provide a powerful working environment for accomplished authors. They enable efficient work even on large complex interrelated text collections. These tools are aimed at experienced authors.
== How it works
Fedora documentation uses the Antora to build and manage the Web site. Documentation is once created static content, with updates from time to time. This is exactly what Antora specializes in. It gathers static text documents and transforms them into a complete Web site, including navigation, links, formatting, positioning, adaptation to different output devices, etc. For more general information about the Antora publishing system, see the https://antora.org/[Antora website] and https://docs.antora.org/antora/latest/page/[Antora documentation].
As a writer, you can fully concentrate on the content and your message and write away.
As a writer, you concentrate on the content and write away.
=== The general procedure
The 4-eyes principle applies to the Fedora documentation. A different author reviews each contribution. Technically, when you complete your text or text modification, the system creates a "Pull Request" or "Merge Request" to integrate your text into the documentation body. This triggers other authors, specifically board members or members specifically committed to the part of the documentation body in question, to start a review and either initiates an inclusion or starts a discussion. Allow 2-3 days for an answer to a request.
The 4-eyes principle applies to the Fedora documentation. A different author reviews each contribution. When you complete your text or text modification, the system creates a "Pull Request" or "Merge Request" to integrate your text into the documentation body. This triggers other authors, board members or members committed to the part of the documentation body in question, to start a review and either initiates an inclusion or starts a discussion. Allow 2 to 3 days for an answer to a request.
=== Some technical background
@ -67,28 +67,26 @@ The only requirements for contributing documentation to Fedora Docs are:
One can distinguish several typical types of contribution to Fedora documentation, for which the available tools are suitable in different ways.
Many ways for various types of contribution, e.g., typo fixes, adding short information or a link, update an article, contribute a new article.
Many ways for various types of contribution. For example, typo fixes, adding short information or a link, update an article, contribute a new article.
=== Update an existing documentation page
This typically involves minor changes, e.g., typo fixes, adding short information or a link, or a correction to the text. This type is especially necessary whenever the documentation needs to be updated due to a new software version.
This task involves minor changes. For example, typo fixes, adding short information or a link, or a correction to the text. This type is especially necessary whenever the documentation needs to be updated due to a new software version.
The _File Edit tools_ are convenient for this purpose.
This is specifically true for _casual contributions_ when a user detects outdated or inaccurate information.
=== Extend an existing documentation domain
This typically involves adding one of more new chapter or section(s) with several chapters, e.g., adding another container technique to the documentation of containerization.
This task involves adding one of more new chapter or section(s) with several chapters. For example, adding another container technique to the documentation of containerization.
The _Web interface_ is a convenient tool for this purpose. A local writing environment is useable as well, but may involve too much overhead, if you want contribute to just one documentation.
It is highly recommended to present the plan on one of the Docs communication channels before starting. You may get suggestions and tips on content, but also on editing, e.g., file structure and naming conventions.
It is highly recommended to present the plan on one of the Docs communication channels before starting. You may get suggestions and tips on content, but also on editing. For example, file structure and naming conventions.
=== Introduce a new documentation area
This typically involves a new extensive subject area, such as new software or a new administration tool. Typically, it includes several sections and chapters and requires the creation of a new, separate repository.
This task involves a new extensive subject area, such as new software or a new administration tool. For example, inclusion of several sections and chapters and the creation of a new, separate repository.
For this type, setting up a local writing environment is useful and worthwhile. However, the web interface would also be usable.
For this type, setting up a local writing environment is useful and worthwhile.
In any case, a prior discussion with the Docs team is necessary, if only to create the technical prerequisites.