Get Involved/documentation: Difference between revisions

From KDE Community Wiki
m (Bcooksley moved page Consistent name/documentation to Get Involved/documentation without leaving a redirect: Fixing mistake.)
(→‎Wikis: Plural)
 
(25 intermediate revisions by 12 users not shown)
Line 1: Line 1:
__NOTOC__
[[File:Mascot konqi-support-document.png|right|x150px]]
== Get Involved with KDE Documentation ==
Writing documentation is a great way to start improving your application and KDE software. Your words will be translated to all languages covered by the KDE translations teams, and you will be helping millions of KDE software users to better understand their desktop and applications. Anyone with reasonable English skills and good knowledge of an application can help.
 
There are four major types of documentation you can work on.
 
* Wikis
* Tutorials
* Application manuals
* API documentation
 
== Wikis ==
 
The official [https://wiki.kde.org/ KDE wikis] use [https://www.mediawiki.org/wiki/MediaWiki Mediawiki] internally, like Wikipedia, so they will feel familiar if you have ever contributed to Wikipedia or many other wikis.
 
To contribute to the KDE wikis, you should read the [https://userbase.kde.org/Quick_Start Quick Start] page. You may also want to look at the [https://userbase.kde.org/Typographical_Guidelines Typographical Guidelines], [https://userbase.kde.org/Tasks_and_Tools Tasks and Tools], and the [https://userbase.kde.org/Special:MyLanguage/Toolbox Toolbox] pages.
 
The contribution model works like so: you add the content first, and then someone else may review it (it is not guaranteed). If you want to discuss an addition that was made or will be made, you can use that wiki page's Discussion section, collaborate with the [https://community.kde.org/KDE.org KDE Web] team, or make an issue over the [https://invent.kde.org/teams/web/wiki-sites/-/issues/ Wikis Issue Tracker].
 
{{Warning | The Techbase wiki is going away as soon as its content is ported elsewhere. Please consider contributing to [https://userbase.kde.org/ Userbase], [https://community.kde.org/ Community] or [https://invent.kde.org/documentation/develop-kde-org Develop] instead. If you'd like to contribute to porting the content from Techbase, we have [https://invent.kde.org/teams/web/wiki-sites/-/issues/1 an issue with tasks you can work on].}}
 
== Tutorials ==
 
Our [https://develop.kde.org/ developer tutorials] use Markdown and Hugo, and are hosted on [https://invent.kde.org/documentation/develop-kde-org develop-kde-org].
 
To contribute to it, we provide [https://develop.kde.org/docs/contribute/formatting/ Formatting Guidelines] and [https://develop.kde.org/docs/contribute/style/ Style Guidelines].
 
The contribution model works like so: you [https://community.kde.org/Infrastructure/GitLab#Submitting_a_merge_request create a Merge Request] and it gets reviewed before it gets in. This is to ensure the quality of documentation, but if you find it overwhelming, say so, and another contributor will make the necessary changes after your contribution is accepted and merged.
 
It is most often done in collaboration with the [https://community.kde.org/KDE.org KDE Web] team.
 
== Application Manuals ==
 
Our application manuals can be checked online on [https://docs.kde.org/ docs.kde.org], and it uses Docbook, which uses XML and can be converted to several other file formats easily.
 
To contribute to application manuals, you should read the [https://l10n.kde.org/docs/gettingstarted.php Getting Started with Documentation] page, which links to our [https://l10n.kde.org/docs/doc-primer/index.html Documentation Primer].
 
In order to document KDE projects, you will want to run a recent [[Guidelines_and_HOWTOs/Build_from_source | development version of KDE software]]. To document third-party projects, you will also need a recent version of that program. There is a special [http://l10n.kde.org/docs/tools.php KDE DocBook XML toolchain] used to create documentation.
 
The contribution model works like so: to add new content, you send an email to the [https://mail.kde.org/mailman/listinfo/kde-doc-english kde-doc-english mailing list] with the draft that will become the application manual, then you will get feedback on your work and other contributors will help you get the new content in. When the Docbook is finished, either by you or by someone else, it gets added to the project's repository on [https://invent.kde.org/ Invent].
 
{{Note | You do not necessarily need to write in Docbook in order to get your contribution accepted. You may write it in a format you are comfortable with, and request another contributor to convert it to Docbook for you.}}
 
Alternatively, if you are already familiar with Docbook, you may contribute directly to an existing Docbook file in the project's repository by [https://community.kde.org/Infrastructure/GitLab#Submitting_a_merge_request creating a Merge Request]. It then gets reviewed before it gets in.
 
It is managed entirely by the Documentation Team.
 
== API Documentation ==
 
Our [https://api.kde.org API Documentation] is generated with [https://invent.kde.org/frameworks/kapidox KApiDox], which uses [https://www.doxygen.nl/ Doxygen] and [https://invent.kde.org/sdk/doxyqml Doxyqml].
 
To contribute to API documentation, you should read the [https://invent.kde.org/frameworks/kapidox/-/blob/master/README.md KApiDox readme]. You will also need some programming knowledge to figure out what the code does, as well as take a look at [https://www.doxygen.nl/manual/commands.html Doxygen's special commands] and the [https://community.kde.org/Frameworks/Frameworks_Documentation_Policy Frameworks Documentation Policy] to have an idea of what can be used for documenting API.
 
It is important that you do NOT change the API itself unless you know it is harmless (like changing the name of a function parameter).


[[Image:documentation.png|Documentation|left]] Writing documentation is a great way to start improving your application and the KDE project. Your words will be translated to all languages covered by the KDE translations teams, and you will be helping millions of KDE SC users to better understand their desktop and applications. Anyone with reasonable English skills and good knowledge of an application can help.
The contribution model works like so: you [https://community.kde.org/Infrastructure/GitLab#Submitting_a_merge_request create a Merge Request] and it gets reviewed before it gets in.


There are two kinds of documentation in KDE.<br /> Context help explains individual GUI items on the screen, see [http://bddf.ca/~aseigo/whatsthis_tutorial/ Aaron Seigo's guide] on this. The remainder of this page focuses on help documents (application manuals), which include screenshots and explain an application's features and overview.
It is managed by the documentation and development teams.


== Communicating with the team ==
== Communicating with the team ==


There are many ways to get in touch with the team:<br /> You can chat with the team in [irc://irc.kde.org/kde-docs <nowiki>#kde-docs</nowiki>] on irc.freenode.net, or [http://kde.org/support/#irc learn more about IRC].<br /> The team discusses activities on the mailing lists [https://mail.kde.org/mailman/listinfo/kde-docbook kde-docbook] and [https://mail.kde.org/mailman/listinfo/kde-doc-english kde-doc-english], [http://kde.org/support/#mailinglists learn about mailing lists].
There are many ways to get in touch with the team:
 
You can chat with the Documentation Team in the [https://go.kde.org/matrix/#/#kde-docs:kde.org #kde-docs channel on Matrix] or [irc://irc.libera.chat/kde-docs Libera Chat], and written discussion is held over the [https://mail.kde.org/mailman/listinfo/kde-doc-english kde-doc-english mailing list].


== Getting the resources ==
You can chat with the KDE Web Team in the [https://go.kde.org/matrix/#/#kde-www:kde.org #kde-www channel on Matrix] or [irc://irc.libera.chat/kde-www Libera Chat], and written discussion is held over the [https://mail.kde.org/mailman/listinfo/kde-www kde-www mailing list].


In order to document KDE projects, you will want to run a recent [http://techbase.kde.org/Getting_Started/Build development version of KDE]. To document third-party projects, you will also need a recent version of that program. There is a special [http://l10n.kde.org/docs/tools.php KDE DocBook XML toolchain] used to create documentation. But feel free to write docs in any format you want, and the team will convert it for you!
Learn more about [[Matrix]], [[Internet Relay Chat | Libera Chat]] and [http://kde.org/support/#mailinglists Mailing Lists].


== The KDE DocBook format ==
== The KDE DocBook format ==
Line 18: Line 71:
We use the DocBook XML standardized format, which allows for ease of translation using our custom tools. The markup is extremely self-descriptive, and many people find it easier than HTML to learn. However, if you are not familiar with it, please read up about it below. To produce quality documentation, please have a look at these guides:
We use the DocBook XML standardized format, which allows for ease of translation using our custom tools. The markup is extremely self-descriptive, and many people find it easier than HTML to learn. However, if you are not familiar with it, please read up about it below. To produce quality documentation, please have a look at these guides:


* [http://opensource.bureau-cornavin.com/crash-course/ DocBook Crash Course]
<!--* [http://opensource.bureau-cornavin.com/crash-course/ DocBook Crash Course] --- site has moved to www.workshop-chapina.com, but no longer seems to offer the crash course. The same document is found here: -->
* [http://l10n.kde.org/docs/styleguide/index.html The KDE Style Guide] - a complete guide to KDE documentation
* [http://slackermedia.info/sprints/multimediaSprint_v1/ebooks/docbook_crashCourse.pdf DocBook Crash Course]
* [http://l10n.kde.org/docs/markup/index.html The KDE DocBook Authors guide] - covers the minimal customizations KDE makes to the DocBook DTD, and the conventions we use within our documentation
* [http://l10n.kde.org/doc/screenshots.php The screenshots specification]
* [http://l10n.kde.org/doc/screenshots.php The screenshots specification]
<!--* [http://quality.kde.org/develop/howto/howtodocs.php Documentation HOWTO] - more information that should be copied here later-->
<!--* [http://quality.kde.org/develop/howto/howtodocs.php Documentation HOWTO] - more information that should be copied here later-->
Line 27: Line 79:
* [http://l10n.kde.org/docs/questionnaire.php Questions You Should Answer When You Document KDE]
* [http://l10n.kde.org/docs/questionnaire.php Questions You Should Answer When You Document KDE]
* [http://l10n.kde.org/docs/index-script.php The goals of the KDE Editorial Team]
* [http://l10n.kde.org/docs/index-script.php The goals of the KDE Editorial Team]
* [http://opensource.bureau-cornavin.com/crash-course/ Crash-course to DocBook]
* [http://l10n.kde.org/docs/tools.php The KDE DocBook XML toolchain]
* [http://l10n.kde.org/docs/tools.php The KDE DocBook XML toolchain]


== Tasks ==
== Tasks ==


Now you have a recent version of KDE running, you can get you first contribution committed today! Here are some tasks for the beginner:
Now that you have a recent version of KDE running, you can get your first contribution committed today! Here are some tasks for beginners:


* [http://l10n.kde.org/docs/current.php Open Documentation Tasks] - a list of the few documentation priorities
* [http://l10n.kde.org/docs/current.php Open Documentation Tasks] - a list of the few documentation priorities
Line 38: Line 89:
* [https://bugs.kde.org/buglist.cgi?short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr&long_desc=&product=docs&component=Corrections&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED Bugzilla listing of documentation] that needs to be updated
* [https://bugs.kde.org/buglist.cgi?short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr&long_desc=&product=docs&component=Corrections&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED Bugzilla listing of documentation] that needs to be updated
* [https://bugs.kde.org/buglist.cgi?short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr&long_desc=&product=docs&component=Missing+content&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED Bugzilla listing of applications] missing documentation
* [https://bugs.kde.org/buglist.cgi?short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr&long_desc=&product=docs&component=Missing+content&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED Bugzilla listing of applications] missing documentation
* [http://techbase.kde.org/Projects/Documentation/KDE4 Techbase Documentation page]
* [http://techbase.kde.org/Projects/Documentation/KDE Techbase Documentation page]
* [http://techbase.kde.org/Projects/Documentation/KDE4_(health_table) Documentation Status]
* [http://techbase.kde.org/Projects/Documentation/KDE_(health_table) Documentation Status]
* Mail in your creations to [mailto:[email protected] the KDE documentation team].
* Mail in your creations to [mailto:[email protected] the KDE documentation team].


== Mentor program ==
== Mentor program ==


Getting started in a big project can be hard. Here are some people that are willing to help you one-on-one:
Getting started with a big project can be hard. Here are some people that are willing to help you one-on-one:
 
* Burkhard Lück (<span class="mailme">lueck at hube-lueck dot de</span>) : documentation


* Burkhard Lück (<span class="mailme">lueck at hube-lueck dot de</span>)<br /> documentation
* Yuri Chornoivan (<span class="mailme">yurchor at ukr dot net</span>) : documentation
* Yuri Chornoivan (<span class="mailme">yurchor at ukr dot net</span>)<br /> documentation
 
* volunteer to mentor!<br /> your name here
* Thiago Sueto (<span class="mailme">thiago dot sueto at kde dot org</span>) : wikis, tutorials and API docs
 
* volunteer to mentor! Add your name here
 
[[Category:Needs Attention]]
__NOTOC__

Latest revision as of 13:41, 11 April 2024

Writing documentation is a great way to start improving your application and KDE software. Your words will be translated to all languages covered by the KDE translations teams, and you will be helping millions of KDE software users to better understand their desktop and applications. Anyone with reasonable English skills and good knowledge of an application can help.

There are four major types of documentation you can work on.

  • Wikis
  • Tutorials
  • Application manuals
  • API documentation

Wikis

The official KDE wikis use Mediawiki internally, like Wikipedia, so they will feel familiar if you have ever contributed to Wikipedia or many other wikis.

To contribute to the KDE wikis, you should read the Quick Start page. You may also want to look at the Typographical Guidelines, Tasks and Tools, and the Toolbox pages.

The contribution model works like so: you add the content first, and then someone else may review it (it is not guaranteed). If you want to discuss an addition that was made or will be made, you can use that wiki page's Discussion section, collaborate with the KDE Web team, or make an issue over the Wikis Issue Tracker.

Warning

The Techbase wiki is going away as soon as its content is ported elsewhere. Please consider contributing to Userbase, Community or Develop instead. If you'd like to contribute to porting the content from Techbase, we have an issue with tasks you can work on.


Tutorials

Our developer tutorials use Markdown and Hugo, and are hosted on develop-kde-org.

To contribute to it, we provide Formatting Guidelines and Style Guidelines.

The contribution model works like so: you create a Merge Request and it gets reviewed before it gets in. This is to ensure the quality of documentation, but if you find it overwhelming, say so, and another contributor will make the necessary changes after your contribution is accepted and merged.

It is most often done in collaboration with the KDE Web team.

Application Manuals

Our application manuals can be checked online on docs.kde.org, and it uses Docbook, which uses XML and can be converted to several other file formats easily.

To contribute to application manuals, you should read the Getting Started with Documentation page, which links to our Documentation Primer.

In order to document KDE projects, you will want to run a recent development version of KDE software. To document third-party projects, you will also need a recent version of that program. There is a special KDE DocBook XML toolchain used to create documentation.

The contribution model works like so: to add new content, you send an email to the kde-doc-english mailing list with the draft that will become the application manual, then you will get feedback on your work and other contributors will help you get the new content in. When the Docbook is finished, either by you or by someone else, it gets added to the project's repository on Invent.

Note

You do not necessarily need to write in Docbook in order to get your contribution accepted. You may write it in a format you are comfortable with, and request another contributor to convert it to Docbook for you.


Alternatively, if you are already familiar with Docbook, you may contribute directly to an existing Docbook file in the project's repository by creating a Merge Request. It then gets reviewed before it gets in.

It is managed entirely by the Documentation Team.

API Documentation

Our API Documentation is generated with KApiDox, which uses Doxygen and Doxyqml.

To contribute to API documentation, you should read the KApiDox readme. You will also need some programming knowledge to figure out what the code does, as well as take a look at Doxygen's special commands and the Frameworks Documentation Policy to have an idea of what can be used for documenting API.

It is important that you do NOT change the API itself unless you know it is harmless (like changing the name of a function parameter).

The contribution model works like so: you create a Merge Request and it gets reviewed before it gets in.

It is managed by the documentation and development teams.

Communicating with the team

There are many ways to get in touch with the team:

You can chat with the Documentation Team in the #kde-docs channel on Matrix or Libera Chat, and written discussion is held over the kde-doc-english mailing list.

You can chat with the KDE Web Team in the #kde-www channel on Matrix or Libera Chat, and written discussion is held over the kde-www mailing list.

Learn more about Matrix, Libera Chat and Mailing Lists.

The KDE DocBook format

We use the DocBook XML standardized format, which allows for ease of translation using our custom tools. The markup is extremely self-descriptive, and many people find it easier than HTML to learn. However, if you are not familiar with it, please read up about it below. To produce quality documentation, please have a look at these guides:

Tasks

Now that you have a recent version of KDE running, you can get your first contribution committed today! Here are some tasks for beginners:

Mentor program

Getting started with a big project can be hard. Here are some people that are willing to help you one-on-one:

  • Burkhard Lück (lueck at hube-lueck dot de) : documentation
  • Yuri Chornoivan (yurchor at ukr dot net) : documentation
  • Thiago Sueto (thiago dot sueto at kde dot org) : wikis, tutorials and API docs
  • volunteer to mentor! Add your name here