< Server | Documentation
m (Some text additions.) |
|||
| Line 18: | Line 18: | ||
To download a not yet published version, go to the "''Branches''" tab in the left navigation column. In the "'''stg'''" row select the left most icon "code tree for this branch". The file list then displayed contains a ''stg'' at the top. Follow the directory tree under ''docs'' to the ''pages'' directory. Check the browser address field. It should contain '''blob/stg''' near the base address. Select the appropriate document file. | To download a not yet published version, go to the "''Branches''" tab in the left navigation column. In the "'''stg'''" row select the left most icon "code tree for this branch". The file list then displayed contains a ''stg'' at the top. Follow the directory tree under ''docs'' to the ''pages'' directory. Check the browser address field. It should contain '''blob/stg''' near the base address. Select the appropriate document file. | ||
"Right click" onto the ''RAW'' button and select "Save Link As ..." (Firefox). In the dialog that opens, save the file to a suitable location on your workstation. | |||
You can edit the document using any text editor. For convenience you should use an asciidoc editor. We recommend AsciidocFX (https://asciidocfx.com). It is quite slim yet sophisticated, and available for all operating systems. The editor includes a preview, which of course can only be an approximation due to the lack of site-specific CSS, but contains the essential elements. | You can edit the document using any text editor. For convenience you should use an asciidoc editor. We recommend AsciidocFX (https://asciidocfx.com). It is quite slim yet sophisticated, and available for all operating systems. The editor includes a preview, which of course can only be an approximation due to the lack of site-specific CSS, but contains the essential elements. | ||
| Line 25: | Line 27: | ||
== Setting up an authoring environment == | == Setting up an authoring environment == | ||
Fedora Server documentation is at: https://pagure.io/fedora-server/. | |||
It includes the content as well as various scripts to build and preview the site locally. The directory structure is predefined by the docs Content Management System (Andorra) and must not be changed. | |||
It has 2 permanent branches: „main“ for the published content and „stg“ for planning, development, and discussion. Temporarily, additional branches may also be present. | |||
For up- and download you can use either https or ssh. For people with FAS account ssh may be more convenient. | |||
The workflow folllow the Fedora docs project „[https://docs.fedoraproject.org/en-US/fedora-docs/contributing/git/ Git for docs writers]“. Each contributor should create a fork of the repository for themselves. Contributions are uploaded to the fork and then transferred to the authoritative version via a pull request. This opens up the possibility for others to comment and initiate a broader discussion. | |||
Revision as of 07:05, 27 June 2021
We provide several ways to contribute.
- You may send us an email, e.g. while reading a document on our Web pages.
- You may download a document, make changes and send it back.
- You may create a complete authoring environment using Git and Podman / Docker
Sending an e-mail with proposed changes
A very simple and straightforward approach is indicated when something catches your eye while reading an article, or when you are conducting a review of a single document. Just write your suggestions in the form of "current version" - "proposed version" in an email and send it either to the Fedora Server list, server@lists.fedoraproject.org, or directly to the server documentation coordinator (currently pboy@fedoraproject.org). Suggestions will then be included in the text, or perhaps there will be follow-up questions.
Download a document
If the suggested changes are more extensive or consist of very short elements, e.g. typo corrections, it is probably easier to download that one document from our server and change it.
The repository base address is https://pagure.io/fedora-server.
To download a published version, go to the "Files" tab in the left navigation column, then to docs and further along the directory tree to pages. Check the browser address field. It should contain main near the base address. Select the appropriate document file.
To download a not yet published version, go to the "Branches" tab in the left navigation column. In the "stg" row select the left most icon "code tree for this branch". The file list then displayed contains a stg at the top. Follow the directory tree under docs to the pages directory. Check the browser address field. It should contain blob/stg near the base address. Select the appropriate document file.
"Right click" onto the RAW button and select "Save Link As ..." (Firefox). In the dialog that opens, save the file to a suitable location on your workstation.
You can edit the document using any text editor. For convenience you should use an asciidoc editor. We recommend AsciidocFX (https://asciidocfx.com). It is quite slim yet sophisticated, and available for all operating systems. The editor includes a preview, which of course can only be an approximation due to the lack of site-specific CSS, but contains the essential elements.
After completion of the editing send the file by email directly to the server documentation coordinator (currently pboy@fedoraproject.org).
Setting up an authoring environment
Fedora Server documentation is at: https://pagure.io/fedora-server/.
It includes the content as well as various scripts to build and preview the site locally. The directory structure is predefined by the docs Content Management System (Andorra) and must not be changed.
It has 2 permanent branches: „main“ for the published content and „stg“ for planning, development, and discussion. Temporarily, additional branches may also be present.
For up- and download you can use either https or ssh. For people with FAS account ssh may be more convenient.
The workflow folllow the Fedora docs project „Git for docs writers“. Each contributor should create a fork of the repository for themselves. Contributions are uploaded to the fork and then transferred to the authoritative version via a pull request. This opens up the possibility for others to comment and initiate a broader discussion.