Difference between revisions of "Help:Contribute"

Jump to: navigation, search
(Added links to markup guides)
Line 1: Line 1:
You are welcome to contribute to the KDE TechBase wiki. To maintain high quality content and articles there are a few guidelines you should follow. This is a brief introduction to editing and contributing.
+
<languages/>
  
'''Looking for Formatting Guides'''?  See the [https://en.wikipedia.org/wiki/Help:Cheatsheet Markup Cheatsheet] or the comprehensive [https://en.wikipedia.org/wiki/Help:Wiki_markup Markup Guide].
+
<translate>This page contains information about editing the KDE TechBase wiki, including what content belongs where and helpful tools specific to this wiki. Even if you are familiar with wikis, you should read [[#Organisation|the section on organisation]] to see what content should be put where on this wiki.
  
== What Content belongs in KDE TechBase ==
+
==Before you Start==
  
'''KDE Techbase is the primary place for high quality technical information about KDE targeted at 3rd party developers, ISVs, distributors and system administrators.'''
+
===First Things First===
  
Techbase is the place where technical people who aren't necessarily part of the community should find all information they need to get started with KDE. This covers development of KDE application, administration of KDE installations, or distributing KDE software. The content is of high quality and stability, and includes tutorials, information about release schedules and policies, technical background information and answers to frequently asked questions.
+
* To contribute to TechBase you must register an account with the [https://identity.kde.org KDE Identity service], then activate it on [https://phabricator.kde.org Phabricator] by logging in there, and then you can click the [[Special:PhabricatorLogin/redirect|Login with Phabricator]] link on the sidebar to log in.
  
Techbase doesn't require its users to be involved in the community, be subscribed to any KDE mailing lists or any other community internal sources of information to be able to fully understand and use the provided information. Developers working on KDE applications will find useful content on techbase as far as it overlaps with the needs of 3rd party developers, but they are not the primary audience of techbase.
+
* Be aware that you must agree to your contributions to this wiki being released under the licenses listed at [[KDE TechBase:Copyrights]]. These licenses mean that what you write might be copied to other sites, for example.
  
More details can be found in the article [[Help:Wiki Structure]].  
+
* Use the [https://www.mediawiki.org/wiki/Help:Talk_pages Talk pages] to communicate with other contributors or get help.  Normally someone will get back to you within a day.
  
For end-user documentation use [http://userbase.kde.org KDE UserBase]. For community info, particularly sharing information among KDE developers and contributors, use the [http://community.kde.org KDE Community Wiki]. See the [http://wiki.kde.org Wiki Landing Page] for an overview.
+
===Relevance===
  
=== Where to put new Articles ===
+
This wiki is for documentation for developers wanting to use or extend KDE products. This includes:
  
The KDE TechBase wiki uses subpages. Take a quick look at the article about the [[Help:Wiki Structure]]. In short: Do not randomly add toplevel pages.
+
* overview information for libraries, including the advantages of using them
 +
* tutorials and examples for using libraries
 +
* tutorials, examples and documentation for writing plugins and other extensions to libraries and applications
 +
* IPC/RPC interfaces for software, like DBus interfaces
  
It is possible to translate KDE TechBase articles into other languages. Read the article about [[Help:Wiki Translation]] for further details.
+
End-user documentation belongs on [https://userbase.kde.org UserBase], and things directed at contributors, teams and the KDE Community in general belong on [https://community.kde.org the community wiki]. Examples of things that don't belong on TechBase include:
  
=== The Procedure ===
+
* documentation on how to use an application
 +
* code style policies
 +
* information for new contributors
 +
* team coordination (TODO lists, meeting notes, etc)
 +
* notes on the internal architecture of a piece of software (but the architecture of a library's API does belong)
  
You want to add new content. To keep high quality, please create the article in your userpage first (e.g. User:foo/My Acticle). Once it is ready, discuss the article with other developers and proofread it. Finally, if a location is found, move the page.
+
==Organisation==
  
After moving the page please '''add yourself to the watch list''' by clicking the ''Watch'' register. You will get a notice by mail whenever the page changes.
+
This wiki is organised using [https://www.mediawiki.org/wiki/Help:Subpages subpages]. This is a parent-child relation. For example, if we consider the [[Policies/Licensing Policy]] page, '''Policies''' is the ''parent'' of '''Licensing Policy''' and '''Licensing Policy''' is a ''subpage'' (or a child) of '''Policies'''.
  
== Editing Basics ==
+
This structure is useful because it provides a hierarchical organisation in the URL itself, makes page names less likely to clash (for example, many projects will want similarly-named pages) and provides back links (in the above example,  [[Policies/Licensing_Policy]] will contain a link back to [[Policies]] near the top).
  
You need to register to be able to edit pages.
+
{{TODO|need to document the structure}}
 
=== Review Policy and Conventions ===
 
  
Make sure that you submit information which is relevant to the specific purpose of the wiki, or your content might be deleted. You can always use the [[Help:Talk page|''Discussion'' or ''talk'' pages]] to ask questions or to check if your idea will be accepted. Please make sure your contributions are not violating any licenses.
+
==Formatting==
  
=== Start Editing ===
+
* The main MediaWiki site has [http://www.mediawiki.org/wiki/Help:Formatting a Wiki syntax guide]
 +
* UserBase has some [https://userbase.kde.org/Toolbox lists of formatting] that can be a useful reference, including templates that are specific to the KDE wikis.
 +
* Much of what applies to Wikipedia (except the templates) also applies here, including [http://en.wikipedia.org/wiki/Help:Wiki_markup Wiki markup] and their [http://en.wikipedia.org/wiki/Wikipedia:Cheatsheet cheatsheet].
  
To start editing a [[Main Page|KDE TechBase]] page, click the '''Edit''' link at the tab on the top. This brings you to the edit page: a page with a text box containing the ''wikitext'' - the editable code from which the server produces the finished page. ''If you just want to experiment, please do so in the [[Sandbox|sandbox]], not here''.
+
==Wiki Maintenance==
  
=== Type your Changes ===
+
Maintaining a clean and useful wiki involves making sure content is up to date, there are no broken links, and all pages can be found (they are linked to from somewhere). The following special pages can help find issues that need fixing:
  
You can just type your text. However, also using basic wiki markup to make links and do simple formatting increases the value of your contribution. Please follow the style used in other wiki articles. If you follow this, your contributions will be more valuable as they won't need to be cleaned up later.
+
; Issues which should be fixed as soon as possible
 +
:[[Special:Lonelypages]]
 +
:[[Special:BrokenRedirects]]
 +
:[[Special:DoubleRedirects]]
  
=== Summarize your Changes ===
+
; Issues which should be fixed in time
 +
:[[Special:Wantedpages]]
 +
:[[Special:Wantedcategories]]
  
Write a short edit summary in the small field below the edit-box.
+
You can also add a page to the [[:Category:Needs Attention|Needs Attention]] to flag it for later work by adding <nowiki>[[Category:Needs Attention]]</nowiki> to the page. Using [[Template:TODO]] will also add a page to this category.
  
Example: "Fixed a typo"
+
===Deleting pages===
  
=== Preview before Saving ===
+
Most users cannot delete pages on the Wiki - this is because once a page is gone, you cannot get it back. If you think a page should be deleted, mark it with [[Template:Proposed_deletion]] at the top:
  
When you have finished, click '''Show preview''' to see how your changes will look '''before''' you make them permanent.  Repeat the edit/preview process until you are satisfied, then click '''Save page''' and your changes will be immediately applied to the article.
+
{{Input|1=<nowiki>{{Proposed_deletion|reason=this page contains only spam}}</nowiki>}}
 
+
</translate>
== Wiki Markup Reference ==
 
 
 
The wikipedia provides a quick introduction about the most important mediawiki syntax. Please read the [http://en.wikipedia.org/wiki/Wikipedia:How_to_edit_a_page Page editing help].
 

Revision as of 16:41, 10 March 2016

Other languages:
English • ‎français • ‎português do Brasil

This page contains information about editing the KDE TechBase wiki, including what content belongs where and helpful tools specific to this wiki. Even if you are familiar with wikis, you should read the section on organisation to see what content should be put where on this wiki.

Before you Start

First Things First

  • Be aware that you must agree to your contributions to this wiki being released under the licenses listed at KDE TechBase:Copyrights. These licenses mean that what you write might be copied to other sites, for example.
  • Use the Talk pages to communicate with other contributors or get help. Normally someone will get back to you within a day.

Relevance

This wiki is for documentation for developers wanting to use or extend KDE products. This includes:

  • overview information for libraries, including the advantages of using them
  • tutorials and examples for using libraries
  • tutorials, examples and documentation for writing plugins and other extensions to libraries and applications
  • IPC/RPC interfaces for software, like DBus interfaces

End-user documentation belongs on UserBase, and things directed at contributors, teams and the KDE Community in general belong on the community wiki. Examples of things that don't belong on TechBase include:

  • documentation on how to use an application
  • code style policies
  • information for new contributors
  • team coordination (TODO lists, meeting notes, etc)
  • notes on the internal architecture of a piece of software (but the architecture of a library's API does belong)

Organisation

This wiki is organised using subpages. This is a parent-child relation. For example, if we consider the Policies/Licensing Policy page, Policies is the parent of Licensing Policy and Licensing Policy is a subpage (or a child) of Policies.

This structure is useful because it provides a hierarchical organisation in the URL itself, makes page names less likely to clash (for example, many projects will want similarly-named pages) and provides back links (in the above example, Policies/Licensing_Policy will contain a link back to Policies near the top).

noframe
 
TODO
need to document the structure

Formatting

Wiki Maintenance

Maintaining a clean and useful wiki involves making sure content is up to date, there are no broken links, and all pages can be found (they are linked to from somewhere). The following special pages can help find issues that need fixing:

Issues which should be fixed as soon as possible
Special:Lonelypages
Special:BrokenRedirects
Special:DoubleRedirects
Issues which should be fixed in time
Special:Wantedpages
Special:Wantedcategories

You can also add a page to the Needs Attention to flag it for later work by adding [[Category:Needs Attention]] to the page. Using Template:TODO will also add a page to this category.

Deleting pages

Most users cannot delete pages on the Wiki - this is because once a page is gone, you cannot get it back. If you think a page should be deleted, mark it with Template:Proposed_deletion at the top:

{{Proposed_deletion|reason=this page contains only spam}}

Content is available under Creative Commons License SA 4.0 unless otherwise noted.