Writing Documentation: Procedures and Tools
If you are worried about having to learn a lot of new tools and procedures in order to write documentation, you do not need to, because the information we've covered so far is everything you need to know to be able to contribute. Although we do have some tools we use and procedures we follow, it is not vital that everyone knows them in detail, especially when starting out.
For example, all documentation is written in DocBook , but we're very happy to receive documentation written in plain text. There are people on the documentation team who are very familiar with DocBook, and can easily add the markup if the content is there.
Another example: if you are starting to document an application from scratch, you do not need to get the sources of the current documentation. But if you are starting from existing documentation, you do not need to know about how to get the sources, there are other means to do that.
Of course, if you want to learn about DocBook, you can. After a little practice, you will probably find that it is not as hard as it looks. And if you learn about dealing with a Git repository, you will be able to integrate yourself to the regular Git development process (upload your changes, work together with other developers, )

Getting the Documentation Sources
If you are starting your document from scratch, you probably do not need to read this section, and may start working right now.
You are welcome to use plain text to contribute to documentation. It is a great way to start, and we strongly encourage it. If you will miss the power of the DocBook format as you improve your documentation skills, then you can learn it. In the meantime, someone will manually edit the plain text to add the DocBook markup and commit it to Git repository, removing the burden of doing most of the more complex stuff covered in this very guide. We'll take a look at writing in DocBook and using Git later in this document, so if you are interested, read on, but if you want to use plain text, you can go directly to Working with plain text sources.
Documentation for , like the rest of the source code, is kept in Git repositories. Git provides a way for many developers to work on the same source code (or in our case, the same documentation), and has many useful features to help with this. For example, previous versions of every file are saved so that any mistakes can be quickly backed out, if they can't be easily corrected.
The basic principle behind Git is simple: one server stores a definitive copy of the files making up a project. This is known as the repository. Each developer can clone the repository to work on the code. Using Git, the developers can upload their modifications to the main repository (a process called "committing") or update their own clone to reflect recent changes made by others.
There are two main ways edit the contents of a document you want to improve: using plain text or DocBook.

Working with plain text sources
The docs.kde.org website displays most of the documentation in format, updated weekly from the Git repository. There are two versions available on the website: the stable version based on kdelibs 4 or Frameworks 5 and the development versions based on kdelibs 4 or Frameworks 5. You will always use the latest version of the documentation.
The docs.kde.org website presents a quick and easy method of retrieving the latest version of the documentation. Clicking the name of the application you want to document in the list will open the documentation in your web browser. Simply copy the text from the website to your favorite text editor, edit it , and submit the results in plain text to the Documentation mailing list, kde-doc-english@kde.org. Please note that not all applications are listed there. If you cannot find the documentation of the application you want to work with, then you can request it by sending a message to the Documentation mailing list.

Retrieving the DocBook sources
The latest DocBook sources are located inside the Git repositories. Now you need to find and retrieve them.
To access the repository, you can use the git command line application or browse the repositories.
The site is a web based representation of all Git repositories. It is easy to download files using theProjects page, the operating system or desktop you use does not matter.
Retrieving your own working copy of the repository has many advantages. You will be able to use your working copy to create files containing the changes you made, to update your copy with changes made by other documenters, and if you get a contributor account, to upload your changes directly to the repository. But this is out of the scope of this section. Here we will show you simply how to retrieve the sources using Git the easiest way we can.

Retrieving documentation sources
Go to Projects page using your favorite web browser. Let's suppose you are looking for Lokalize's documentation sources.
Search for lokalize on this page and click on tree to display the repository.
Now click on doc and all Lokalize's documentation files will be displayed, being images or DocBook files.
Now you reached the list of files that are part of Lokalize's documentation, including images and DocBook sources. The DocBook sources are files in the format *.docbook. In this case, there is only one file in this format: index.docbook. Click this file on the list and the content of that file will be displayed.
It is the most recent one. Save the file. Repeat this process with all the files you want to download.
We use Lokalize's documentation sources as example in the following procedures.

Retrieving documentation sources using Git
Check if you have the Git client installed (hint: enter git in the terminal screen). If not, install the Git package using the tools provided by your distribution.
Now it is time to download, or clone the sources. Using Git, type in the terminal:

git clone git://anongit.kde.org/lokalize.git

Using
is an extensible and powerful text editor. can syntax highlight DocBook documents out of the box, and is generally a very powerful editor, but you can get even more XML specific functionality by installing the XML plugin for .

Installing the XML plugin for
The XML plugin for is available as part of the repository. Binary packages are available for the majority of the distributions. Install the binary package using your distribution tools or compile to install the plugin.
Open the Configure dialog by choosing the Settings Configure ... menu item.
Select the Plugins item from the Application tree. Check the XML Completion and the XML Validation boxes.
A screenshot of 's Plugin Manager Configure Dialog
A screenshot of 's Plugin Manager Configure Dialog
A screenshot of 's Plugin Manager Configure Dialog
Press OK.
With the XML plugin for installed, you will have autocompletion, autoclosing for DocBook tags and entities. Since documentation uses entities widely, this is a very welcome feature. Additional XML tools will be available through the XML menu (especially through the Validate XML menu item, which will allow you to check your DocBook documents). The output of this action will appear in the XML Checker Output button in the sidebar located in the lower part of 's main window.
A screenshot of 's Main Window showing the XML Checker Output
A screenshot of 's Main Window showing the XML Checker Output
A screenshot of 's Main Window showing the XML Checker Output

Checking and Viewing the Documents
There are a couple of -specific tools for manipulating DocBook files, namely meinproc5 and checkXML5. checkXML5 (as the name suggests) is used to check that documents are valid, well-formed , and meinproc5 converts DocBook files to . Here's some hints on using each of them:

Using checkXML5
checkXML5 is a simple command with only one argument: the file to check. However, the output can be a bit daunting, since one small mistake can cause a cascade of errors. The trick is to look at the first error, fix that error, save the file, and run checkXML5 again. Often, fixing that one error will get rid of all the other error messages. When running meinproc5, the same procedure applies.
Most errors in DocBook sources fall into one of a few categories. Here are descriptions of some of the most common errors and their solutions:
Opening and ending tag mismatch 	


index.docbook:880: parser error : Opening and ending tag mismatch: para
line 879 and sect2
</sect2>
        ^

This is possibly the most common type of error. It is caused either by an element that has not been closed, or by tags that overlap. The error above was generated by the following markup:



<sect2>
...
878: running &meinproc5;, the same procedure applies.</para>
879: <para>&checkxml5; is a simple command with
880: </sect2>
...

The para tag on line 879 has not been closed before the sect2 on line 880, causing the error. The simple fix in this case is to add a para before the closing sect2.
Element does not follow the DTD 	


index.docbook:932: element qandaentry: validity error : Element qandaentry content
does not follow the DTD, expecting (blockinfo? , revhistory? , question , answer*), got (answer)
</para></answer></qandaentry>
                             ^

This error is caused by an element in the document not matching the requirements of the DocBook DTD (Document Type Definition). The DTD specifies what each element must contain. This list is shown after expecting in the error message. This so-called content model is quite difficult to understand at first: refer to the Duck Book and the section Understanding Content Models for full information.
The text after got shows the content actually found in the document.
In the example above, we have a qandaentry which is missing the required question element. This was generated by the following input:



<qandaset>
<qandaentry><answer><para>An answer
</para></answer></qandaentry>
</qandaset>

Adding a question element before the answer fixes the problem.
An easy mistake to make is to forget to put a para element around text in, for example, a listitem or a sectn. This will be shown as CDATA in the got section of the error.

Using meinproc5
The most common way to run meinproc5 is simply as

meinproc5 docbook-file

where docbook-file is usually index.docbook. This command creates pages from the DocBook file. Note that these pages are only viewable in -based browsers (like ). If you need to view the output in another browser (for example, if you are placing it on line), use

meinproc5 --stylesheet stylesheet-name docbook-file

where stylesheet-name is the full path to one of the stylesheets found in the kdoctools git repository To produce output suitable for the web, you can use kde-web.xsl or kde-chunk-online.xsl. See the README file in that directory for more details.