Skip to content

docs: feedback for walkthrough #15595

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mcdurdin wants to merge 2 commits into
base: walkthrough
Choose a base branch
from
+218 −125
Open

docs: feedback for walkthrough #15595

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c10a74c
docs: feedback for walkthrough
mcdurdin Feb 17, 2026
1207a01
docs(developer): address review comments on walkthrough
mcdurdin Feb 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 20 additions & 8 deletions developer/docs/help/guides/develop/walkthrough/00-introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,12 @@
title: Introduction
---

[Next: Part 1 - Creating a Keyboard Project >](01-creating-keyboard-project)
<link href='walkthrough.css' rel='stylesheet'>
<div class="walkthrough-navigation" markdown="1">
Introduction to the [Keyman Developer Walkthrough](.).

[Next: Part 1 - Creating a Keyboard Project →](01-creating-keyboard-project)
</div>

Comment on lines +5 to 11
Copy link
Member Author

@mcdurdin mcdurdin Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added some CSS to highlight the navigation, and went back to arrows for clarity

image

## Step-by-Step

Expand All @@ -12,7 +17,7 @@ If you encounter unfamiliar terms, please consult the [glossary](glossary).

### Introducing Keyman Developer

Keyman Developer is a powerful tool you can use to create custom keyboards optimized to type in any language you choose. Keyboard authors can distribute their work for desktop, web, tablet and phone, enabling global communities to quickly benefit from keyboards made for their own language.
Keyman Developer is a powerful tool you can use to create custom software keyboards optimized to type in any language you choose. Keyboard authors can distribute their work for desktop, web, tablet and phone, enabling global communities to quickly benefit from keyboards made for their own language.

Keyboards created with Keyman Developer can be used on Windows, macOS, Linux, iOS, Android, and the web.

Expand All @@ -23,17 +28,19 @@ Currently this software is Windows-only, although the command line tools it uses

Keyman Developer is completely free to download and use. You can download it from [https://keyman.com/developer/download](https://keyman.com/developer/download).

On the downloads page, just click the big green “Download Now” button to get the latest version of Keyman. Once you have it, run the `keymandeveloper.exe` file you’ve received. The numbers following “keymandeveloper” indicate which version of Keyman Developer you are installing.
On the downloads page, just click the big green “Download Now” button to get the latest version of Keyman. Once you have it, run the `keymandeveloper-a.b.c.exe` file you’ve downloaded. The numbers following “keymandeveloper” indicate which version of Keyman Developer you are installing; you can also see the Keyman Developer version in the main installer window, or after installation, in the Help/About dialog.

After installing Keyman Developer, you should be able to run it on your computer and begin creating projects immediately.

Note that Keyman Developer is a separate app from Keyman, which is the app that lets you use any keyboard created with Keyman Developer.
In order to use the keyboard you create with Keyman Developer, you'll need to have the Keyman app installed on your computer or device.
Keyman is available on the following platforms: Windows, macOS, Linux, iOS, Android, and the web.

The icons for Keyman Developer ![Keyman Developer icon](images/keyman-developer-icon.png) and Keyman ![Keyman icon](images/keyman-icon.png) are similar but slightly different.
The Keyman Developer icon ![Keyman Developer icon](images/keyman-developer-icon.png) is a faded version of the Keyman icon ![Keyman icon](images/keyman-icon.png).

<div class="walkthrough-navigation" markdown="1">
To continue the Step-by-Step tutorial move to the next page: [Part 1 - Creating a Keyboard Project](01-creating-keyboard-project)
</div>

---

Expand All @@ -48,9 +55,9 @@ Ask questions and talk with other keyboard authors on the [Keyman Community Foru

### Keyman online help

[Keyman Developer Language Documentation](https://help.keyman.com/developer/language/guide/)
[Keyman Developer Language Guide](https://help.keyman.com/developer/language/guide/)

Reference for the general structure of the Keyman language.
Information about the general structure and concepts of the Keyman language.

[Keyman Developer Language Reference](https://help.keyman.com/developer/language/reference/)

Expand All @@ -69,7 +76,12 @@ Read up on Keyman’s latest releases and patch notes on the [Keyman Blog](https
Keyman uses a number of [Github](https://github.com/keymanapp) repositories to store source code, keyboards, lexical models and documentation.
There is also a mechanism for reporting problems. [Keyman Bug Reports](https://github.com/keymanapp/keyman/issues)

Report Keyman software bugs and issues here. NOTE: NOT for help and support questions. The Keyman community forum is the best place to ask for help with development. Think you’ve found a Keyman bug or a problem with a specific keyboard? Describe what you’ve found on the Keyman community forum and ask whether to report a bug.
Report Keyman software bugs and issues here.

> [!NOTE]
> GitHub issues are not the best place to ask for help or support questions. The Keyman community forum is a better place to ask for help with keyboard development. Think you’ve found a Keyman bug or a problem with a specific keyboard? Describe what you’ve found on the Keyman community forum and ask whether to report a bug.
Comment on lines +81 to +82
Copy link
Member Author

@mcdurdin mcdurdin Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Trying to make the notes look a little cleaner

image


[Next: Part 1 - Creating a Keyboard Project >](01-creating-keyboard-project)
<div class="walkthrough-navigation" markdown="1">
[Next: Part 1 - Creating a Keyboard Project →](01-creating-keyboard-project)
</div>

59 changes: 35 additions & 24 deletions developer/docs/help/guides/develop/walkthrough/01-creating-keyboard-project.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,12 @@
title: Creating a Keyboard Project
---

Part 1 of the [Keyman Developer Walkthrough](../walkthrough).
<link href='walkthrough.css' rel='stylesheet'>
<div class="walkthrough-navigation" markdown="1">
Part 1 of the [Keyman Developer Walkthrough](.).

[< Back: Introduction](00-introduction)

[Next: Part 2 - Designing a Desktop Layout >](02-designing-desktop-layout)
[← Introduction](00-introduction) &nbsp; [Part 2 - Designing a Desktop Layout →](02-designing-desktop-layout)
</div>

## Step-by-Step

Expand All @@ -31,8 +32,9 @@ For the Dagbani keyboard, the keyboard planning has been done for you. Follow th
- Select `OK` to close the `Select BCP 47 tag` dialog.
- Select `OK` to close the `New Basic Keyboard Project` dialog.

<div class="walkthrough-navigation" markdown="1">
To continue the Step-by-Step tutorial move to the next page: [Part 2 - Designing a Desktop Layout](02-designing-desktop-layout)

</div>
---

## Planning a Keyboard
Expand All @@ -41,7 +43,7 @@ The first step is identifying the language or languages your keyboard will cover

- it is difficult to optimize a keyboard for multiple languages since a rarely used character for one language may be a common character for another.
- it is harder for users to find the keyboard since the name of the keyboard may not relate to the particular language they are researching.
- a separate lexical model (for predictive text) is needed for each language, so having a keyboard that handles multiple languages may make installation of a lexical model harder.
- it is more difficult for users to select the correct language for during installation, particularly if a keyboard handles many languages. This is particularly important for lexical models for predictive text, as a separate model is needed for each language.

Furthermore, having a keyboard specifically designed for a single language may help with community acceptance.

Expand Down Expand Up @@ -87,20 +89,23 @@ Note that the `Keyboard ID` (near the bottom of the dialog) fills in automatical
You can modify the value in this field, though you are limited to the characters a-z, the numbers 0-9 and underscore.
This value will be used as the base filename of many of your Keyman files.

If you decide to change the keyboard ID, you’ll need to change most of the files in the project.
This is best done using Keyman Developer’s `Clone local project` feature.

- From the `Project` menu, select `New Project` then `Clone local project`.
- Use the `Browse` button to navigate to the `.kpj` file of your existing project.
- Specify a new `project ID` (and adjust `Destination path` if desired), then select `OK`.
> [!NOTE]
> If you decide to change the keyboard ID, you’ll need to change most of the files in the project. This is best done using Keyman Developer’s `Clone local project` feature.
> • From the `Project` menu, select `New Project` then `Clone local project`.
> • Use the `Browse` button to navigate to the `.kpj` file of your existing project.
> • Specify a new `project ID` (and adjust `Destination path` if desired), then select `OK`.

### Description

This brief description of your keyboard is included in all of your information files.
Try to keep this short but informative, as this is what people will see when searching for your keyboard.
Try to keep this short but informative, as this is what people will see when searching for your keyboard on the keyman.com website.
It may be useful to include alternate language names, the script (Latin, Devanagari, etc)
if the language is written in more than one script, the region where it is used, or other details about the keyboard.

The description field can use [Markdown](https://www.markdownguide.org/cheat-sheet/) for basic formatting and links.

The description is added to `README.md` and the package `.kps` file.

### Author, Copyright, and Full Copyright

Enter your name in the `Author` field.
Expand All @@ -111,20 +116,25 @@ The Full Copyright field has the date as well as the copyright holder.
The name used in the Copyright fields must be the real name of an individual or of an organization.
Copyright cannot be assigned to a pseudonym.

The short copyright message is added to `README.md`, `welcome.htm`, `readme.htm`, package `.kps` details, and the [`&copyright` keyboard system store](https://help.keyman.com/developer/language/reference/copyright) in the `.kmn` file.
The full copyright message is added to `LICENSE.md`.

### Languages

This table displays the [BCP 47](https://help.keyman.com/developer/current-version/reference/bcp-47) tag (or tags) associated with your keyboard.
This table displays the [BCP 47](../../../reference/bcp-47) tag (or tags) associated with your keyboard.
A BCP 47 tag identifies a language and will help users find your keyboard when they search for their language.
If you don’t know what your language’s tag is, you can search for its name and find the corresponding tag in the [IANA Language Subtag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry), which contains all existing BCP 47 tags, the [Glottolog](https://glottolog.org/glottolog/language) (under the ISO-639-3 column), or the [SIL Ethnologue](https://www.ethnologue.com/).

The SIL Ethnologue is the most user-friendly option of the three, if you are unfamiliar with language tags.

In addition to your basic BCP 47 tag, you can add
[Script](https://help.keyman.com/developer/current-version/reference/bcp-47#toc-the-script-subtag) and
[Region](https://help.keyman.com/developer/current-version/reference/bcp-47#toc-the-region-subtag) subtags.
[Script](../../../reference/bcp-47#toc-the-script-subtag) and
[Region](../../../reference/bcp-47#toc-the-region-subtag) subtags.
However, you should always use the simplest possible BCP 47 tag to identify your language.
Only add Script and Region tags if your keyboard is for a script or region that differs from the most commonly used form of the language.

Language information is added to `README.md` and in the package `.kps` file, in the Keyboards section.

### Version

The keyboard version number allows Keyman to tell which of two copies of a keyboard is newer. This allows Keyman to offer users updated versions of keyboards.
Expand All @@ -133,10 +143,11 @@ The version number consists of two or three integer numbers separated by periods

New keyboards usually start with version `1.0` (which is equivalent to `1.0.0`).
Generally the first number is incremented for major changes to the keyboard,
the second for minor changes, and the third for corrections or bug fixes.
But the most important point is that the new version number be greater than the existing one (as noted above).
the second for minor changes, and the third for corrections or bug fixes (this is known as [semantic versioning](https://semver.org); note that Keyman keyboard versions do not allow additional labels).

The version number appears in the `HISTORY.md` file and the `.kmn` file.
The most important point is that the new version number be greater than the existing one (as noted above).

The version number appears in the `HISTORY.md` file and the `.kmn` file in the [`&keyboardversion` keyboard system store](https://help.keyman.com/developer/language/reference/keyboardversion).
It should be updated in both places whenever you distribute a new version of the keyboard.

### Targets
Expand All @@ -148,7 +159,7 @@ If you select `any`, you do not need to (and should not) choose any other option

It is best practice to support as many devices as possible when creating your keyboard, because it is hard to predict who will use your keyboard in the future. By making your keyboard as accessible as possible, you can help even more people.

If you decide not to include a touch layout, untick the `any` option and select `desktop` and `web` which will allow the keyboard to be used on a web page as well as on Linux, macOS and Windows (the three `desktop` platforms). If you later add a touch layout, you can reverse this process and go back to selecting just `any`.
If you decide not to include a touch layout, untick the `any` option and select `desktop` and `web` which will allow the keyboard to be used on a web page as well as on Linux, macOS and Windows (the three `desktop` platforms). If you later add a touch layout, you can reverse this process and go back to selecting just `any` in the [`&targets` keyboard system store](https://help.keyman.com/developer/language/reference/targets).

### Path

Expand All @@ -160,7 +171,7 @@ It’s a good idea to let Keyman handle naming your files, since it uses good na

Once you have filled out all of the fields,
Keyman Developer will create your project and open it in a new window with your project’s `.kpj` (Keyman project) file displayed.
You can read more about the `.kpj` file type in the [official Keyman documentation](https://help.keyman.com/developer/current-version/reference/file-types/kpj).
You can read more about the `.kpj` file type in the [official Keyman documentation](../../../reference/file-types/kpj).

## Basing a new Keyboard Project on an existing one

Expand All @@ -184,6 +195,6 @@ When ready, select `OK` to download the files, adjust the filenames and open the

Now that you have your project set up, continue to the next section of the tutorial to start developing your first keyboard layout.

[< Back: Introduction](00-introduction)

[Next: Part 2 - Designing a Desktop Layout >](02-designing-desktop-layout)
<div class="walkthrough-navigation" markdown="1">
[← Introduction](00-introduction) &nbsp; [Part 2 - Designing a Desktop Layout →](02-designing-desktop-layout)
</div>
24 changes: 14 additions & 10 deletions developer/docs/help/guides/develop/walkthrough/02-designing-desktop-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,12 @@
title: Designing a Desktop Layout
---

Part 2 of the [Keyman Developer Walkthrough](../walkthrough).
<link href='walkthrough.css' rel='stylesheet'>
<div class="walkthrough-navigation" markdown="1">
Part 2 of the [Keyman Developer Walkthrough](.).

[< Back: Part 1 - Creating a Keyboard Project](01-creating-keyboard-project)

[Next: Part 3 - Creating a Desktop Layout >](03-creating-desktop-layout)
[← Part 1 - Creating a Keyboard Project](01-creating-keyboard-project) &nbsp; [Part 3 - Creating a Desktop Layout →](03-creating-desktop-layout)
</div>

## Step-by-Step

Expand All @@ -18,7 +19,9 @@ We’ll start with the default QWERTY layout and add rules so that typing <kbd>;

This Step-by-Step tutorial won’t be using the visual layout features of Keyman Developer for creating the desktop keyboard.

<div class="walkthrough-navigation" markdown="1">
To continue the Step-by-Step tutorial move to the next page: [Part 3 - Creating a Desktop Layout](03-creating-desktop-layout)
</div>

---

Expand Down Expand Up @@ -60,7 +63,7 @@ For visual mapping, this can be done with tools as rudimentary as a pen and pape

Navigate to your `.kpj` file, go to the `Keyboards` tab, and open your `.kmn` file. This is where your keyboard’s information lies, as well as the code that makes it work.

You can read more about the `.kmn` file type in the [official Keyman documentation](https://help.keyman.com/developer/current-version/reference/file-types/kmn).
You can read more about the `.kmn` file type in the [official Keyman documentation](../../../reference/file-types/kmn).

Inside your `.kmn` file, select the `Layout` tab on the left.
For a new project, the `Design` tab (at the bottom) should already be selected.
Expand Down Expand Up @@ -112,7 +115,9 @@ Here’s an example of how to list your keystrokes. (This can also be reused whe
Once you have planned the visual layout of your keyboard and determined how to assign the rest of the keys on the keyboard, it’s time to begin coding.
If your layout is simple enough that you do not need to program additional keys, you do not need to worry as much about the next section.
In some cases, using Keyman’s visual editor is enough for a desktop keyboard.
Note that once you begin adding rules, the keyboard becomes too complex to modify with the visual layout tools, so it is best to do any visual layout work first using the `Design` tab, then add the additional rules using the `Code` tab.

> [!NOTE]
> Once you begin adding multi-part rules, the keyboard becomes too complex to modify with the visual layout tools, so it is best to do any visual layout work first using the `Design` tab, then add the additional rules using the `Code` tab.

### Deadkeys

Expand All @@ -139,7 +144,6 @@ We could choose to design the keyboard so that typing `[ { ] } - _ = + \ |` will
That could be done with the `Design` mode using the visual layout tools, or by adding rules.
We would then want to add rules to allow the user to type the characters that were on the ten keys that we repurposed to type the additional characters, for example type the `;` key then the `[` key to get an actual `[` character.


[< Back: Part 1 - Creating a Keyboard Project](01-creating-keyboard-project)

[Next: Part 3 - Creating a Desktop Layout >](03-creating-desktop-layout)
<div class="walkthrough-navigation" markdown="1">
[← Part 1 - Creating a Keyboard Project](01-creating-keyboard-project) &nbsp; [Part 3 - Creating a Desktop Layout →](03-creating-desktop-layout)
</div>
Loading