KDE Games/Documentation Progress

Purpose

This is the page for the kdegames docs audit.

KDEGames Docteam name list, assignment list and statistics

Games Done

1. lskat
2. KFourInLine
3. Ktuberling
4. Kmahjongg
5. KSpaceDuel
6. KShisen
7. Konquest
8. Kjumpingcube
9. Kbattleship
10. Knetwalk
11. Katomic
12. Kiriki
13. Klines
14. Kbounce
15. Bovo
16. KSudoku
17. Kmines
18. KPat
19. Kblackbox
20. Kreversi
21. Ksquares
22. Kolf

Games in Works

1. Kgoldrunner - Unedited due to time limits.
2. Ksame - Lost and never updated

Docteam Name List

Name	IRC nick	Role
Eugene	it-s	Docbook Editor
	dinounix	Docbook Editor

Docbook writing guidelines

The list of KDEGames Docbook sections:

1. Introduction
2. How to Play
3. Game Rules, Strategies and Tips
4. Interface Overview
5. Frequently Asked Questions
6. Game Configuration
7. Credits and License

Detailed description of sections

Introduction

--Guidelines--

1. Indicate 'Game type:' first. Available game types are: Arcade, Board, Card, Dice, Toys, Logic, Strategy. NOTE: game may have more then one type.
2. Indicate 'Number of possible players:' second. It can be: One, Two,..., Multiplayer
3. Give a short game description. Use a clean and short sentences in passive voice (no you).

• First outline a general game idea.
• Then talk about the same idea in details.
• Conclude with the main goal of the game.

Length: 3-4 sentences.

Sample

Game type: Logic, Arcade

Number of possible players: One

Katomic is both fun and educational game built around molecular geometry. It employs simplistic two-dimensional looks at different chemical elements. Elements are disassembled into separate atoms and scattered around the play field. Player is expected to reassemble the molecule, thus completing current level and moving up to the next one.

How to Play

--Guidelines---

1. State the game objective first. (see sample below)
2. Describe gameplay. (see sample below) Short description of the game process has to follow. Make sure you use simple and clean sentence structure and 'active voice' form.

• • Describe gameplay to the reader.
  • Include all important gameplay details.
  • You may include screenshots* to illustrate your point if necessary. But don't overload.

Length: 8-18 sentences.

Sample

Objective: assemble molecules from compound atoms by sliding the atoms around.

Gameplay: Katomic will load level one once you start the game and you can start playing right away. To see how the molecule you are supposed to make looks like, take a look at the upper right corner. To play, click on an atom. You will see green arrows pointing in the directions where atom can move. To move the atom, click on the desired arrow. When an atom starts moving, it will not stop until it hits another atom or a wall, so make sure you think before you do your next move. You can assemble your molecule where you like on the game board, but some places are better than others. When the molecule is assembled, you can move to the next level.

Game Rules, Strategies and Tips

--Guidelines---

1. Use leveled bulletpoints only
2. There have to two sections here: 'Rules', and 'Strategies and tips'
3. Rules:
   1. All the game dos and don'ts should be described here.
   2. Use passive voice (no you) and clean, short sentence structure.
   3. Length: 6-18 points.
4. Strategies and tips:
   1. Warnings go here.
   2. Any sort of comments that may benefit player directly should go here.
   3. Use active voice (you) and clean, short sentence structure.
   4. Length: 4-12 points.

Sample

Rules:

• Game pieces can only move in one direction at a time.
• Once an atom begins moving it will not stop until it meets either a wall or another peace.
• The only way to progress to the next game level is to complete a current one. *Once player completes a certain level game automatically switches to the next one, thus 'uncovering it'.
• Player can only switch between the levels which have been uncovered.
• The game progress is automatically saved every time an adjacent level is reached, and will be reloaded the next time application is started.

Strategies and tips:

• Always review the complete molecule using the reference screen before making any moves.
• Next, study the play field and plan your moves. Remember, once a piece is moved it may not be possible to return it into the starting position.
• Think through your every move and try to visualize the trajectory piece will follow once a directional arrow is clicked.
• When using keyboard to move pieces make sure that an exact piece is selected. If a wrong atom is marked as selected, use 'Tab' key to switch between the pieces until you reach a desired one.

Interface Overview

--Guidelines--

1. Use leveled bulletpoints only
2. Shortly describe every entry of the menubar.
3. Shortly describe every default shortcut.
4. Use passive voice only (no you)

Length: as much as it takes.

Sample

Menubar:

• Game
  • Load... [Ctrl+O] – load saved game
  • Restart Game [F5] – restart current game
  • Save [Ctrl+S] – save current game
  • Previous Level [Ctrl+P] – switch to the next level
  • Next Level [Ctrl+N] – go back to the previous level
  • Quit [Ctrl+Q] – quit application
• Move
  • Undo [Ctrl+Z] – unto the last move
  • Redo [Ctrl+Shift+Z] – redo the last undone move
  • Undo All – undo all the moves made
  • Redo All – redo all the moves made
• Settings
  • Animation Speed – adjust the speed of onscreen animation
    • Slow
    • Normal
    • Fast
  • Show Toolbar – show or hide toolbar
  • Show Statusbar – show or hide statusbar
  • Configure Shortcuts... - bring up shortcat configuration utility
  • Configure Toolbars... - bring up toolbar configuration utility
• Help
  • Katomic Handbook [F1] – shows this help
  • What's This? [Shift+F1] – draws a question mark (?) beside the mouse pointer. Clicking then on a window item such as a toolbar button will then display a brief explanation
  • Report Bug... - starts bug report wizard
  • About Katomic - displays brief information about the product. Such as version number, authors, contributors, and license agreement.
  • About KDE - displays brief information about KDE. Such as version number, authors and license agreement.

Default keyboard shortcuts

• Restart game - F5
• Cycle atoms - Tab
• Cycle atoms backwards - Shift+Tab
• Highscore table - Ctrl+H
• Load - Ctrl+O
• Quit - Ctrl+Q
• Help - F1
• What's this - Shift+F1
• Redo - Ctrl+Shift+Z
• Undo - Ctrl+Z
• Next level - Ctrl+N
• Previous level - Ctrl+P

Frequently Asked Questions

--Guidelines--

1. Use leveled bulletpoints only
2. Use active voice (you) only.

List of generic questions to use with every game

• Q. Who made this game?
• A. The kdegames team. You can find their website here.

• Q. Where can I get cheatcodes?
• A. You cannot get cheatcodes for KDE games.

• Q. This game is boring, why?
• A. KDE games are not meant to be high-quality FPS games.

• Q. How do I start a new game?

• Q. I have started a new game. What do I do now?

• Q. How do I pause the game?

• Q. I want to change the way this game looks. Can I?

• Q. I have made a mistake. Can I undo?

• Q. Can I skip a level?

• Q. Can I use keyboard?

• Q. Can I change default keyboard shortcuts?
• A. Yes. Select Settings and then Configure Shortcuts.

• Q. I cannot figure out what to do here! Are there hints?

• Q. I have to quit the game now, but I'm not finished yet. Can I save my progress?

• Q. I have saved my progress earlier. How do I restore it?

• Q. Where are the highscores?

• Q. I want to change the game configuration. Where do I go?

• Q. I want to change the toolbar layout. What do I do?

Length: no more then 60 points.

Sample

• Q. How do I start a game?
• A. Katomic loads directly into the game play mode at startup. So, no additional actions are required to start the game.

Users are usually capable of doing this themselves...

• Q. How do I know what does the molecule look like?
• A. You can view the molecule on the reference screen located in the top right corner of the game screen.

• Q. Where is the reference screen?
• A. The reference screen is located in the top right corner of the game screen.

• Q. How do I move a game piece(atom)?
• A. To move a game piece(atom) use your mouse cursor to click on it. At this time the available directional icon will become visible. Click on the corresponding directional icon to make a game piece move in desired direction. Alternatively, you can use your keyboard to move the pieces. Use [Tab] key to switch between the items, and directional key to move them once selected.

• Q. Can I use keyboard to control the pieces(atoms)?
• A. Yes. Use [Tab] key to switch between the items, and directional key to move them once selected.

• Q. When I move a peace (atom) it goes right past the place where I want it. How do I make it stop there?
• A. You don't. Once an atom begins moving, it will not stop until it meets either a wall or another peace.

• Q. I have stuck. How can I restart the game?
• A. To restart Karomic choose 'Game' in the game window menu. There choose 'Restart Game'. Alternatively you can press [F5] key on your keyboard to restart the game.

• Q. I cannot beat the level. Is there a hint system, or a solver?
• A. No. Unfortunately at this time Katomic does not feature a hint system. So the only way to finish a level is to solve it on your own.

• Q. I did something wrong. Can I undo.
• A. Yes. To undo a wrong move select 'Move' from the menubar. Then select 'Undo'. Alternatively you can press [Ctrl+Z] on your keyboard.

Game Configuration

--Guidelines--

1. Sep-by-step describe every option in configuration form.
2. Include screenshots* as you dim necessary. But don't overload.

IMPORTANT NOTES

• Screenshots: '.PNG' and '.JPG' ONLY. NO '.GIF'!
• Screenshot sizes:

Useful Links

• The KDE DocBook Authors guide
• DocBook: The Definitive Guide

A DocBook skeleton to use

<?xml version="1.0" ?>
<!-- IMPORTANT: Please note the 'do not change this!'' notice does not apply to translators. -->
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!-- Define an entity for your application if it is not part of KDE SVN -->
  <!ENTITY kappname "<application>KMyApp</application>"><!-- IMPORTANT: If this is a standard KDE application included and 
  developed in KDE SVN please remove this line and us the line below instead!-->
  <!ENTITY kappname "&kappname;"> <!-- Change this 
From: <!ENTITY kappname "&kmyapplication;">
To:<!ENTITY kappname "&kate;">

IMPORTANT: Please use the variable &kappname; everywhere in this document instead of an actual application name.-->

  <!ENTITY kappversion "1.0"><!-- Application version. Use this variable everywhere it's needed.-->
  <!ENTITY docversion "1.0"><!-- Document version. Use this variable everywhere it's needed.-->
  <!ENTITY docupdate "YYYY-MM-DD"><!-- Document version. Use this variable everywhere it's needed.-->
  <!ENTITY package "kdegames">  <!-- do not change this! -->
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
  <!ENTITY % addindex "IGNORE"> <!-- do not change this! -->
]>

<book lang="&language;"> <!-- do not change this! -->
<bookinfo>
	<title>&kappname; Handbook</title> <!-- This is the title of the docbook. Leave as-is unless change is necessary.-->
<!-- List of immediate authors begins here. -->
<!--INPORTANT! - All other contributors: [to be determined] -->
<authorgroup>
        <author><!-- please use the entities in contributor.entities for these -->
        <personname>
		<firstname>First name</firstname> <!-- Author's first name. -->
		 <othername>N.</othername> <!-- Middle / other name. -->
		<surname>Last name</surname> <!-- Author's last name. -->
        </personname>
        <email>email address</email>
	</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<date>&docupdate;</date><!-- Date of (re)writing, or update. Use the variable definitions within header to change this value.-->
<releaseinfo>&docversion;</releaseinfo><!-- Application version number. Use the variable definitions within header to change this value.-->

<!--Short description of this document. Do not change unless necessary!-->
<abstract>
	<para>This documentation describes the game of &kappname; version &kappversion;</para>
</abstract>

<!--List of relevant keywords-->
<keywordset>
	<keyword>KDE</keyword> <!-- do not change this! -->
	<keyword>kdegames</keyword> <!-- do not change this! -->
	<keyword>game</keyword> <!-- do not change this! -->
	<keyword>Application Name</keyword><!--Application name goes here-->
<!-- Game genre. use as many as necessary.Available game types are: Arcade, Board, Card, Dice, Toys, Logic, Strategy.-->
	<keyword>arcade</keyword>
	<keyword>card</keyword>
	<keyword>card game</keyword>
	<keyword>playing cards</keyword>
<!--Number of possible players. It can be: One, Two,..., Multiplayer-->
	<keyword>two players</keyword>
<!--All other relevant keywords-->
	<keyword>skat</keyword>
	<keyword>lieutenant</keyword>
	<keyword>lskat</keyword>
</keywordset>
</bookinfo>
<!-- Content begins here: -->
<chapter id="introduction"><title>Introduction</title> <!-- do not change this! -->
	<note><title>Gametype:</title><para>Card, Arcade</para></note><!-- Game genre. use as many as necessary.Available game types are: Arcade, Board, Card, Dice, Toys, Logic, Strategy.-->
	<note><title>Number of possible players:</title><para>Two</para></note><!-- Number of possible players. It can be: One, Two,..., Multiplayer-->

<!-- Short game description starts here. 3-4 sentences (paragraphs)-->
	<para>
	Short game description.
	</para>
</chapter>

<chapter id="howto"><title>How to play</title> <!-- do not change this! -->
<!-- IMPORTANT: If the game has no defined objective, please remove the below line.-->
	<note><title>Objective:</title><para>Score more then 60 points in a single game.</para></note><!-- Describe the objective of the game.-->
<!-- How to play description. Don't be too specific on rules as they have a separate section in this document-->
	<para>
	How to play description.
	</para>
</chapter>

<chapter id="rules_and_tips"><title>Game Rules, Strategies and Tips</title> <!-- do not change this! -->
	<!-- This section has to do with game rules. Please give a detailed description of those using lists or paragraphs.-->
	<para>Game Rules, Strategies and Tips</para>	
</chapter>


<chapter id="interface"><title>Interface Overview</title> <!-- do not change this! -->
<!-- This section covers the menubar. Describe every single entry in order. Use <variablelist> and <varlistentry>. 
Split the chapter into sections using <sect1(2,3)> for better viewing.-->

<sect1 id="help"><!-- This is a standard Help menubar entry. Only change if needed.-->
<title>The <guimenuitem>Help</guimenuitem> Menu</title>
&help.menu.documentation;
</sect1>
</chapter>


<chapter id="faq"><title>Frequently asked questions</title> <!-- do not change this! -->
<!-- This chapter is for frequently asked questions. Please use <qandaset> <qandaentry> only!-->
<qandaset>
<!-- Following is a standard list of FAQ questions.-->
<qandaentry>
<question><para>Who made this game?</para></question>
 <answer><para>The kdegames team. You can find their website <ulink url="http://games.kde.org/">here</ulink>.</para></answer>
</qandaentry>
<qandaentry>
 <question><para>Where can I get cheatcodes? </para></question>
 <answer><para>You cannot get cheatcodes for &kde; games.</para></answer>
</qandaentry>
<qandaentry>
 <question><para>How do I start a new game? </para></question>
 <answer><para>Explain how to start a new game here.</para></answer>
</qandaentry>
<qandaentry>
 <question><para>How do I pause the game? </para></question>
 <answer><para>Explain how to pause game here.</para></answer>
</qandaentry>
<qandaentry>
 <question><para>I want to change the way this game looks. Can I? </para></question>
 <answer><para>Explain how the theme selector works.</para></answer>
</qandaentry>
<qandaentry>
 <question><para>I have made a mistake. Can I undo? </para></question>
 <answer><para>Explain how to undo here.</para></answer>
</qandaentry>
<qandaentry>
 <question><para>Can I use keyboard? </para></question>
 <answer><para>Answer Yes/No and explain how if positive.</para></answer>
</qandaentry>
<qandaentry>
 <question><para>I cannot figure out what to do here! Are there hints? </para></question>
 <answer><para>Explain how to use feature if exists. If not, write: '&kappname; does not have this feature.', but do not remove the question.</para></answer>
</qandaentry>
<qandaentry>
 <question><para>I have to quit the game now, but I am not finished yet. Can I save my progress?</para></question>
  <answer><para>Explain how to use feature if exists. If not, write: '&kappname; does not have this feature.', but do not remove the question.</para></answer>
</qandaentry>
<qandaentry>
 <question><para>Where are the highscores?</para></question>
 <answer><para>Explain how to use feature if exists. If not, write: '&kappname; does not have this feature.', but do not remove the question.</para></answer>
</qandaentry>
<qandaentry>
 <question><para>I want to change the game configuration. Where do I go? </para></question>
 <answer><para>Refer to <!--<link linkend="menu-settings">this</link> uncomment when needed--> section of 'Interface Overview' for details.</para></answer><!--IMPORTANT!: this link has to send user to 'Interface Overview' section. So please setup the link structure accordingly.-->
</qandaentry>
<qandaentry>
 <question><para>I want to change the toolbar layout. What do I do?</para></question>
 <answer><para>Refer to <!--<link linkend="menu-settings">this</link> uncomment when needed--> section of 'Interface Overview' for details.</para></answer>
 <!-- IMPORTANT!: this link has to send user to 'Interface Overview' section. So please setup the link structure accordingly.-->
</qandaentry>
<!--Please add more Q&As if needed-->

</qandaset>
</chapter>

<chapter id="configuration"><title>Game Configuration</title> <!-- do not change this! -->
<!-- This section describes configuration GUI. If your game is configured using menubar exclusively, please remove this section.-->
<para>This section describes configuration &gui;.</para>
</chapter>

<chapter id="credits"><title>Credits and License</title> <!-- do not change this! -->
<!-- This chapter is for credits and licenses.-->

<para>
&kappname;  <!-- do not change this! -->
</para>
<!-- List all the copyright holders here-->
<para>
Program copyright [year from]-[year to] [first name] [last name] <email>[email address]</email>
</para>
<para>
Graphics copyright [year to] [first name] [last name] <email>[email address]</email>
</para>
<para>
Documentation copyright [year from]-[year to] [first name] [last name] <email>[email address]</email>
</para>


<!-- !!!do not change ANYTHING after this line!!!! -->
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;
&underGPL;

</chapter>


<appendix id="installation">
<title>Installation</title>

&install.intro.documentation;


<sect1 id="Compilation">
<title>Compilation and Installation</title>

&install.compile.documentation;

</sect1>
</appendix>

&documentation.index; 
</book>
<!--
Local Variables:
mode: xml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-omittag:t
sgml-shorttag:t
sgml-namecase-general:t
sgml-always-quote-attributes:t
sgml-indent-step:0
sgml-indent-data:nil
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab
kate: space-indent on; indent-width 2; tab-width 2; indent-mode none;
-->