From 98566ec560769551927149edd2eff42f29d2682e Mon Sep 17 00:00:00 2001 From: pboy Date: Apr 24 2023 21:31:03 +0000 Subject: First version of new page documentation maintenance --- diff --git a/wg/modules/ROOT/assets/attachments/archive/._FedoraServerDocpageProposal_v1-0.pdf b/wg/modules/ROOT/assets/attachments/archive/._FedoraServerDocpageProposal_v1-0.pdf new file mode 100644 index 0000000..4ca327f Binary files /dev/null and b/wg/modules/ROOT/assets/attachments/archive/._FedoraServerDocpageProposal_v1-0.pdf differ diff --git a/wg/modules/ROOT/assets/attachments/archive/FedoraServerDocpageProposal_v1-0.pdf b/wg/modules/ROOT/assets/attachments/archive/FedoraServerDocpageProposal_v1-0.pdf new file mode 100644 index 0000000..1354a68 Binary files /dev/null and b/wg/modules/ROOT/assets/attachments/archive/FedoraServerDocpageProposal_v1-0.pdf differ diff --git a/wg/modules/ROOT/assets/images/archive/._webui-editor-0010.png b/wg/modules/ROOT/assets/images/archive/._webui-editor-0010.png new file mode 100644 index 0000000..211f556 Binary files /dev/null and b/wg/modules/ROOT/assets/images/archive/._webui-editor-0010.png differ diff --git a/wg/modules/ROOT/assets/images/archive/._webui-editor-0020.png b/wg/modules/ROOT/assets/images/archive/._webui-editor-0020.png new file mode 100644 index 0000000..6ad79f3 Binary files /dev/null and b/wg/modules/ROOT/assets/images/archive/._webui-editor-0020.png differ diff --git a/wg/modules/ROOT/assets/images/archive/webui-editor-0010.png b/wg/modules/ROOT/assets/images/archive/webui-editor-0010.png new file mode 100644 index 0000000..3a40af3 Binary files /dev/null and b/wg/modules/ROOT/assets/images/archive/webui-editor-0010.png differ diff --git a/wg/modules/ROOT/assets/images/archive/webui-editor-0020.png b/wg/modules/ROOT/assets/images/archive/webui-editor-0020.png new file mode 100644 index 0000000..baffbd6 Binary files /dev/null and b/wg/modules/ROOT/assets/images/archive/webui-editor-0020.png differ diff --git a/wg/modules/ROOT/nav.adoc b/wg/modules/ROOT/nav.adoc index c318e45..3628357 100644 --- a/wg/modules/ROOT/nav.adoc +++ b/wg/modules/ROOT/nav.adoc @@ -11,4 +11,7 @@ ** xref:wg-minutes-2022.adoc[Meeting minutes 2022] ** xref:wg-minutes-2021.adoc[Meeting minutes 2020/2021] ** xref:wg-minutes-2013.adoc[Meeting minutes prior to 2021] +* xref:usr-docs-maintenance/index.adoc[User Docs Maintenance] +** xref:usr-docs-maintenance/webui-page-editor.adoc[Working with the Web based page editor] +** xref:usr-docs-maintenance/local-authoring.adoc[Working in a local authoring environment] * xref:archive/index.adoc[Archive of Older Pages] diff --git a/wg/modules/ROOT/pages/archive/index.adoc b/wg/modules/ROOT/pages/archive/index.adoc index af6dce7..b93ef1d 100644 --- a/wg/modules/ROOT/pages/archive/index.adoc +++ b/wg/modules/ROOT/pages/archive/index.adoc @@ -1,6 +1,11 @@ = Archive +The Fedora Server Edition Working Group +:page-authors: {author} +// :revnumber: F37-F38 +:revdate: 2023-04-24 For reference and documentation of the Server Edition evolution process, we continue to provide older versions of various documents for review. * xref:archive/product-requirements-document-2014.adoc[Initial version of the "Product Requirements Document" as of 2014] -* xref:archive/product-requirements-document-2021.adoc[Renwed 2021 version of the "Product Requirements Document"] \ No newline at end of file +* xref:archive/product-requirements-document-2021.adoc[Renwed 2021 version of the "Product Requirements Document"] +* WG work project xref:archive/initial-docs-plan.adoc[Buildup of a renewed documentation on Fedora Server specific topics] planning \ No newline at end of file diff --git a/wg/modules/ROOT/pages/archive/initial-docs-plan.adoc b/wg/modules/ROOT/pages/archive/initial-docs-plan.adoc new file mode 100644 index 0000000..2938c1f --- /dev/null +++ b/wg/modules/ROOT/pages/archive/initial-docs-plan.adoc @@ -0,0 +1,107 @@ += Buildup of a renewed documentation on Fedora Server specific topics +The Fedora Server Edition Working Group +:page-authors: {author} +// :revnumber: F37-F38 +// :revdate: 2023-04-xx + +[NOTE] +==== +*Archived Content* Initial planning to build up a server user documentation. +==== + +== Goals == + +* Build up a documentation which will be part of the fedora link:https://docs.fedoraproject.org[docs landing page] +* Maybe: Additional information to central "System Administrator's Guide" documentation +* Maybe: Additional information to the central "Installation Guide" + + +== Planned content for start of publication == + +.First Start Content +[width="100%",options="header"] +|==================== +| Page | Author | Reviewer | Status +| Landing Page | pboy | pwsmith | done & ready +| Server Installation | pboy | nirik | done & ready +| Installation on SBC | pboy | swefredde | done & ready +| Server Administration | pboy | eseyman | done & ready +| Server Post installation tasks | pboy | nirik | done & ready +| Server Virtualisation | pboy | swefredde | done & ready +| Add Virtualisation Support | pboy | swefredde | done & ready +| VMs based on Cloud Images | pboy| IRC WG | done & ready +| FAQ | copperi | IRC WG | done & ready +| Getting in Touch | copperi | IRC WG | done & ready +|==================== + +=== Reviewer tasks === +* Check for technical and content accuracy. Contact the author in case of questions. +* Checking spelling and syntax +* Especially in the case of non-English speaking authors refine the wording and phrases + +To to get the document files and to provide feedback follow the "how to Contribute" information. + +== How to Contribute == + +There are several ways to contribute. A non-intrusive way allows to comment or add to a single document. For longer-term engagement, it makes sense to set up a complete authoring environment. + +Details are described on a [https://fedoraproject.org/wiki/Server/Documentation/How_To_Contribute separate page ]. + +== The next steps == + +* Concretization of the planning. We need +** a rough overall plan of the content +** exemplary topics / themes +** to find contributors / authors + +* Set up Working Environment +** Staging Area +** Preparation of publishing pipelines + +* Define Milestones +** Most important: minimum requirement for going online + +== Preliminary planning proposal == + +Recently I came across an informative article: link:https://opensource.com/article/20/4/documentation?utm_campaign=intrel["What is good documentation for software projects?"]. It's not brand new, but it's a good summary of what to look for in a documentation project. + +=== Team === +We need skill sets from multiple roles  + +* *Authors/Writers* with a deep understanding of the software being described, who create texts, of course +* *Information Architects* who understands how to structure material +* *Reviewers* with a deep understanding of the software being described, who ensure technical correctness +* *Editor/Reader*, especially English native speakers, who proofread the wording and spelling +* *Administrator* who keeps up the build pipelines and correct web formatting and presentation +* *Coordinator*, who keeps an eye on the overall plan and helps to align all the processes and people + +=== Guidelines === + +Notes on the structure of the texts. For example, it would be necessary to regulate: + +* Specification of author(s), date of creation, last update, Fedora version with which representations were tested. +* Start with a short summary of the subject matter, objective and desired outcome. (paragraph of 2-3 sentences) +* Divide longer sequences into sections with subheadings and short explanations +* Provide each step with a brief explanation/justification, if possible, a general instruction structure and a concrete example. + +=== Overall Conceptualization of Server Documentation Content === + +As a first Draft we may discuss (see also +//xref:{attachmentsdir}/archive/FedoraServerDocpageProposal_v1-0.pdf[first draft of a proposal] +//xref:attachments$archive/FedoraServerDocpageProposal_v1-0.pdf[first draft of a proposal] +link:{attachmentsdir}/archive/FedoraServerDocpageProposal_v1-0.pdf[first draft of a proposal] +for a concept to improve documentation) + +* Navigation Items +** Home / Landing Page Fedora Server Documentation +** Post-installation Procedures / Security Hardening +** Fedora Server Example Use Cases +** Tutorials +** Trouble Shooting Guide / Known Issues +** People, policies, and Working Methods +* Details Home / Landing Page +* Details Post Installation +* Details Example Use Cases +* Details Tutorials +* Details People, Policies, ... + diff --git a/wg/modules/ROOT/pages/index.adoc b/wg/modules/ROOT/pages/index.adoc index 3f17f7d..6455375 100644 --- a/wg/modules/ROOT/pages/index.adoc +++ b/wg/modules/ROOT/pages/index.adoc @@ -1,7 +1,7 @@ = Fedora Server Working Group -Peter Boy, Stephen Daley -:page-authors: {author}, {author_2} -:revnumber: all +The Fedora Server Edition working group; Peter Boy (pboy); Stephen Daley (mowest) +:page-authors: {author}, {author_2}, {author_3} +// :revnumber: all :revdate: 2023-04-18 :page-authors: {author} @@ -24,28 +24,30 @@ You will find here information about the overall ideas and goals behind Fedora S Here you will not find any user documentation for Fedora Server Edition, nor any information on why and how to employ a Fedora Server. We maintain a dedicated https://docs.fedoraproject.org/en-US/fedora-server/[Fedora Server user documentation] for that purpose. ==== -== Our Vision +== Our vision Anyone should be able to confidently obtain, configure and deploy software services that address their needs using readily-available and trustworthy recipes. (https://meetbot.fedoraproject.org/fedora-meeting-1/2016-09-06/serversig.2016-09-06-20.00.html[September 6, 2016 meeting]). -== Our Mission +== Our mission Fedora Server Edition is an ecosystem ideal for creating and operating validated service roles addressing most computing needs (https://meetbot.fedoraproject.org/fedora-meeting-1/2016-09-06/serversig.2016-09-06-20.00.html[September 6, 2016 meeting]). -== Currently Ongoing Work Projects +== Currently ongoing long term work projects -1. https://fedoraproject.org/wiki/Server/Documentation[Buildup of a renewed documentation on Fedora Server specific topics] -2. https://fedoraproject.org/wiki/Server/Using_Ansible[Facilitated deployment of key services by combining rpm and Ansible] -3. https://pagure.io/fedora-server/issue/53[Facilitated and improved support for Fedora Server Edition VMs] -4. https://fedoraproject.org/wiki/Server/Off-Premise-Kickstart[Improved support for off-premise Kickstart and pxe installation] -5. Revisiting defaults... filesystem/partitioning -6. Easy integration into multi-node environments with tools like Ansible -== Completed or Deferred Work Projects +. https://fedoraproject.org/wiki/Server/Using_Ansible[Facilitated deployment of key services by combining rpm and Ansible] +≈ +. https://fedoraproject.org/wiki/Server/Off-Premise-Kickstart[Improved support for off-premise Kickstart and pxe installation] +. Revisiting defaults... filesystem/partitioning +. Easy integration into multi-node environments with tools like Ansible + +== Completed or deferred work projects 1. xref:docs/product-requirements-document.adoc[Revision of the Fedora Server 'Product Requirement Document' (PRD)] (finalized IRC 2021-06-23) 2. https://pagure.io/fedora-server/issue/68[Explore opportunities for cooperation with Cloud WG / SIG] +3. xref:archive/initial-docs-plan.adoc[Buildup of a renewed documentation on Fedora Server specific topics] (finalized end of 2021) +4. https://pagure.io/fedora-server/issue/53[Facilitated and improved support for Fedora Server Edition VMs] (finalized mid 2022) -== You Are Welcome to Contribute +== You are welcome to join and to contribute You don’t have to be a programmer, a developer or a technical nerd to contribute to the development of Fedora Server. We are especially interested in feedback from our users and potential new users. diff --git a/wg/modules/ROOT/pages/usr-docs-maintenance/index.adoc b/wg/modules/ROOT/pages/usr-docs-maintenance/index.adoc new file mode 100644 index 0000000..89abc9f --- /dev/null +++ b/wg/modules/ROOT/pages/usr-docs-maintenance/index.adoc @@ -0,0 +1,75 @@ += User Documentation Maintenance +The Fedora Server Edition working group; Peter Boy (pboy); Stephen Daley (mowest) +:page-authors: {author}, {author_2}, {author_3} +// :revnumber: F37-F38 +:revdate: 2023-04-24 + +== Goals + +We want to and maintain a Fedora Server Edition user documentation and keep it up to date on an ongoing basis that + +* focuses on the specific features and procedures of the Fedora Server Edition +* also includes brief explanations and rationales that convey the meaning and underlying concepts +* contains copy-and-paste capable instructions that allow even less experienced administrators to operate safely and reliably +* refers to the upstream documentation for general information, where available + +== Organization + +Fedora uses Antorra CMS to create the documentation WEB site und stores all documents in various git repositories. The Fedora Server documentation is part of the link:https://pagure.io/fedora-server[Fedora Server repository] in the docs subdirectory. + +The pubic user documentation is available at https://docs.fedoraproject.org/en-US/fedora-server/ + +== Contributions + +Authors as well as users should be able to contribute to Fedora Server documentation with as little effort as possible and without technical hurdles. We provide several ways to contribute. + +1. The most common way for casual contributions is to open a ticket and describe the issue, and maybe to make a proposal. +2. Edit the page in question using a Web-based page editor. +3. Set up and work in a local authoring environment on your desktop. +4. You may send us an email, e.g. while reading a document on our Web pages. +//5. You may download a document, make changes and send it back. + + +=== Open a ticket (problem report) + +When reading a document, you see a "bug" button on the rightmost side below the blue top bar. Klick and you are forwarded to create an issue. Members of the Working Group are notified and will take care of it. However, you must have a Fedora account, so you can log in. + +=== Edit a page via a Web Editor + +Besides the aforementioned "bug" button there is a button that stylizes pen and note. It leads to a web-based editor that can be used to make changes to this very page. These are not applied directly, but members of the documentation team are notified for a review. Detailed Information comming soon. + +=== Working in a local authoring environment + +For longer-term engagement, it makes sense to set up a complete authoring environment. It requires some preparations, but provides the most powerful set of tools. A separate page will provide detailed information. + +=== Sending an email + +Someone whe can't use one of the above options because they don't have a FAS account, may just write their suggestions or feedback in an email to the Fedora Server list, server@lists.fedoraproject.org, or post a message on our link:https://discussion.fedoraproject.org/tags/c/project/7/server-wg[discussion board]. You have to register, but it is less effort than creating a FAS account. It's best to use a form like "current version" - "proposed version". Suggestions will then be included in the text, or perhaps there will be follow-up questions. + +== Quality assurance + +Prior to publication, each article should be reviewed. Such articles are available in our link:https://docs.stg.fedoraproject.org/en-US/fedora-server/[staging area] and marked as "awaiting review" or similar. + +Reviewer should + +* check for technical and content accuracy. Contact the author in case of questions. +* check spelling and syntax +* refine the wording and phrases, especially in the case of non-English speaking authors + +The link:https://docs.stg.fedoraproject.org/en-US/fedora-server/[staging area] also contains articles at an early stage of development, allowing for early subject matter exchange and idea collection. + +Furthermore, the published pages are mirrored, giving a complete impression of the later documentation. + + +== Guidelines + +The article link:https://opensource.com/article/20/4/documentation?utm_campaign=intrel[What is good documentation for software projects?] provides a good summary of what we want to achieve with documentation, although it is not entirely new. + +Some pointers for articles: + +* Include of author(s), date of creation, last update, Fedora version with which examples were tested. +* Start with a short summary of the subject matter, objective and desired outcome. (one paragraph of 2-3 sentences) +* Divide longer sequences into sections with subheadings and short explanations +* Provide each step with a brief explanation/justification, if possible, a general instruction structure and a concrete example. + + diff --git a/wg/modules/ROOT/pages/usr-docs-maintenance/local-authoring.adoc b/wg/modules/ROOT/pages/usr-docs-maintenance/local-authoring.adoc new file mode 100644 index 0000000..c856247 --- /dev/null +++ b/wg/modules/ROOT/pages/usr-docs-maintenance/local-authoring.adoc @@ -0,0 +1,113 @@ += Setting up a local authoring envireonment +The Fedora Server Edition working group; Peter Boy (pboy); Stephen Daley (mowest) +:page-authors: {author}, {author_2}, {author_3} +// :revnumber: F37-F38 +:revdate: 2023-04-23 + +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. + +== Preparations + +1. *Create a local subdirectory* where the files of the documentation should be stored, and make it to your default. We use fedora-server-docs in your home throughout this guide ++ + […]$ mkdir ~/fedora-server-docs + […]$ cd ~/fedora-server-docs + + 2. Still in your default working directory, *clone fedora-server* repository + + + […]$ git clone https://git@pagure.io/fedora-server.git -o upstream + + + Git will copy the complete server repo including all branches, specifically „main“ and „stg“ mentioned above, into a local repo on your local workstation (into _.git/_ located in your default directory). + + + Git does „tag“ the cloned repo as remote repo „*upstream*“. + + + At the same time it checks out the default branch „''main''“ into your ''working directory'' (i.e. ~/fedora-server-docs in the above example). Therefore, when the operation terminates, you will find in your current default directory, which is now your ''working directory'', some files, e.g. README.md, build.sh and preview.sh and a directory docs. The latter contains the content. + + + If you leave off „./“ at the end, git creates another directory in your default directory with the name of the repository, i.e. fedora-server. And this directory is then the "_working directory_" to the repository. This can be useful if you want to keep track of different fedora docs projects in one directory. + +3. In your browser go to https://pagure.io/fedora-server/, log in and *create a Fork*. Once you have done it, the button will read _View fork_. Switch to your fork and click on Clone and you will see 2 addresses you can use to clone (copy) the content to your local default directory ++ + ssh://git@pagure.io/forks/[MY_FAS]/fedora-server.git + https://git@pagure.io/forks/[MY_FAS]/fedora-server.git ++ +Still in your default working directory, add the forked Repo to your remote repos. ++ + […]$ git remote add origin ssh://git@pagure.io/forks/[MY_FAS]/fedora-server.git ++ +You can use https as well. For users with a FAS account ssh is usually the better choice. + +4. You have now 2 remote repos defined. Check: ++ + […]$ git remote -v + origin ssh://git@pagure.io/forks/[MY_FAS]/fedora-server.git (fetch) + origin ssh://git@pagure.io/forks/[MY_FAS]/fedora-server.git (push) + upstream https://git@pagure.io/fedora-server.git (fetch) + upstream https://git@pagure.io/fedora-server.git (push) ++ +In your workflow you will update your local version to the latest versions of the server repository by „pulling“ the content from „upstream“ and upload your modifications and additions by „pushing“ it to origin, i.e. to your fork. You will than create a „pull requuest“, i.e. pick up your modifications and additions from your fork and integrate it into the generic repository („origin“). This enables co-writers to review our work and comment on it. + +5. In your working directory create the *built und preview* ++ + […]$ ./build.sh && ./preview.sh + +6, Back to your browser enter the *local preview address*': _localhost:8080_ +* +You should see a local preview of the current Server documentation + +=== Working on content === + +1. Check, if you are on the branch to intend to work on ++ + […]$ git branch + main + * stg + +2. If not, switch to the branch you want to use. ++ + […]$ git checkout [stg|main] ++ +Git will adjust and modify the content of your working directory accordingly! + +3. Before your begin to work update your working directory + […]$ git commit -m „“ + +4. Modify content + +5. Update preview and check: + […]$ ./build.sh && ./preview.sh ++ +Preview in your browser using the address _'localhost:8080_ + +6. Repeat step 4 & 5 as required. + + +=== Save Your Work + +Commit your work locally and then push it into your fork „_origin_“. + +1. Check status ++ + […]$ git status + +2. Add files to commit stage as appropriate ++ + […]$ git add + +3. Commit locally + […]$ git commit -m „“ + +4. Transfer to your fork of fedora server repository ++ + […]$ git push origin [main|stg] + +5. In your browser open https://pagure.io/fedora-server, login, switch to your fork, and create a pull request. + + diff --git a/wg/modules/ROOT/pages/usr-docs-maintenance/webui-page-editor.adoc b/wg/modules/ROOT/pages/usr-docs-maintenance/webui-page-editor.adoc new file mode 100644 index 0000000..8b13473 --- /dev/null +++ b/wg/modules/ROOT/pages/usr-docs-maintenance/webui-page-editor.adoc @@ -0,0 +1,22 @@ += Working with the Web based Page Editor +The Fedora Server Edition working group; Peter Boy (pboy); Stephen Daley (mowest) +:page-authors: {author}, {author_2}, {author_3} +// :revnumber: F37-F38 +:revdate: 2023-04-24 + +As an example, you may want to propose a modificaten of the local interactive installation guide. + +image::archive/webui-editor-0010.png[Editor button] + +At the top you see an editor button. It opens the pagure web page editor. + +image::archive/webui-editor-0020.png[Fork & Edit button] + +Before you can do anything, you have to log in with your Fedora account. Then, the option Fork and Edit gives you the option to directly modify the page content. + +The Fedora Server Edition working group and Pagure follow the "Pull Request Workflow". According to this, no one is supposed to change a published page immediately, but the workflow creates a copy of the page under your name (the "fork") and when you are done, the community is informed about your proposal (the pull request, or PR for short). The community can discuss the proposal and after agreement the administrator can "pull in" the proposal. The process is also known as "merge request" (MR). + +The pagure Web Editor takes care of all the details "behind the scenes". You don't need to worry about it. Just proceed to edit the page. + +More details to follow soon. +