From Fedora Project Wiki
(Add contributor, fix a typo and British to American English)
(Updated documentation review)
 
(9 intermediate revisions by the same user not shown)
Line 12: Line 12:
* '''[[User:copperi | Jan Kuparinen]]''' (copperi) Contributor
* '''[[User:copperi | Jan Kuparinen]]''' (copperi) Contributor
* more to add (hopefully)
* more to add (hopefully)
'''[https://fedoraproject.org/wiki/Server/Documentation/How_To_Contribute How to Contribute ]'''
}}
}}
|}
|}




= Goals =  
== Goals ==  


* Build up a documentation which will be part of the fedora [https://docs.fedoraproject.org docs landing page (docs.fedoraproject.org)]
* Build up a documentation which will be part of the fedora [https://docs.fedoraproject.org docs landing page (docs.fedoraproject.org)]
Line 22: Line 25:
* Maybe: Additional information to the central [https://docs.fedoraproject.org/en-US/fedora/f33/install-guide/ "Installation Guide"]  
* Maybe: Additional information to the central [https://docs.fedoraproject.org/en-US/fedora/f33/install-guide/ "Installation Guide"]  


= The next steps =
== Current content for publication ==
 
{|
! Page !! author !! Reviewer !! Status
|-
| [https://fedoraproject.org/wiki/Help:Wiki_syntax_and_markup#Tables Landing Page] 
| pboy
| pwsmith
| done & ready
|-
| [https://docs.fedoraproject.org/en-US/fedora-server/server-installation/ Server Installation] 
| pboy
| nirik
| done & ready
|-
| [https://docs.fedoraproject.org/en-US/fedora-server/server-installation-sbc/ Installation on SBC] 
| pboy
| swefredde
| done & ready
|-
| [https://docs.fedoraproject.org/en-US/fedora-server/server-administration/ Server Administration] 
| pboy
| eseyman
| done & ready
|-
| [https://docs.fedoraproject.org/en-US/fedora-server/sysadmin-postinstall/ Server Post installation tasks] 
| pboy
| nirik
| done & ready
|-
| [https://docs.fedoraproject.org/en-US/fedora-server/server-virtualization/ Server Virtualisation ] 
| pboy
| swefredde
| done & ready
|-
| [https://docs.fedoraproject.org/en-US/fedora-server/virtualization-install/ Add Virtualisation Support ] 
| pboy
| swefredde
| done & ready
|-
| [https://docs.fedoraproject.org/en-US/fedora-server/virtualization-vmcloud/ VMs based on Cloud Images ] 
| pboy
| IRC WG
| done & ready
|-
| [https://docs.fedoraproject.org/en-US/fedora-server/server-faq/ FAQ ] 
| copperi   
| IRC WG
| done & ready
|-
| [https://docs.fedoraproject.org/en-US/fedora-server/server-communicating/ 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 [[Server/Documentation/How_To_Contribute|"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
* Concretization of the planning. We need
Line 36: Line 107:
** Most important: minimum requirement for going online
** Most important: minimum requirement for going online


= Preliminary planning proposal =
== Preliminary planning proposal ==


Recently I came across an informative article: : [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.  
Recently I came across an informative article: : [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.  

Latest revision as of 17:46, 12 June 2021

Note.png
There is no documentation here.
This page is about planning and organizing work on Fedora Server documentation.
Idea.png
Server Documentation Team
Activists How to Contribute


Goals

Current content for publication

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 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: : "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: A 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, ...