docs(developer): Add Developer walkthrough tutorial by DavidLRowe · Pull Request #15447 · keymanapp/keyman

DavidLRowe · 2026-01-16T04:48:54Z

TODO:

Links from existing content --> docs: remove old content that is deprecated by walkthrough #15710
Compare old tutorials for content match
Retire old tutorials --> docs: remove old content that is deprecated by walkthrough #15710
We want to eliminate the other tutorials over time, so we should avoid referencing them in 03-creating-desktop-layout

"A summary of the elements of the Keyman header can be found in part of another tutorial and detailed information is in the official Keyman documentation:"
The walkthrough belongs at the same level as the 'Keyman Developer Guides' topic /guides/walkthrough, rather than guides/develop/walkthrough [MD] --> docs: move walkthrough up one level #15711
Avoid confusion in following paragraph in 03-creating-desktop-layout --> docs: tweak walkthrough content #15712

Note that rules created when using the Design tab use virtual key codes rather than the corresponding characters. This does not matter unless you are writing a mnemonic layout keyboard. Keyman keyboards are positional by default, so unless you specify a mnemonic layout in your header, the following two lines of code will produce the same output:
Move 'interpreting errors' section from 04-using-debugger --> docs: tweak walkthrough content #15712

Interpreting Errors

This section feels like it would belong better elsewhere, under creating-desktop-layout, probably

Post-merge TODO:

Promote

Build-bot: skip
Test-bot: skip

keymanapp-test-bot · 2026-01-16T04:49:05Z

User Test Results

Test specification and instructions

User tests are not required

DavidLRowe · 2026-01-16T04:49:33Z

Test-bot: skip.

Not sure if this is needed?!

darcywong00 · 2026-01-16T08:54:39Z

Not sure if this is needed?!

I think you edit the PR description and have at the bottom of the text area:

Test-bot: skip

darcywong00

Thanks for the extensive work in migrating this from Notion!

Just a few initial comments for now. Some may warrant more discussion before making changes throughout.

darcywong00 · 2026-01-26T03:37:22Z

+
+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.
+
+Keyboards created with Keyman Developer can be used on Windows, Mac, Linux, iOS, Android, and the web.


I think we generally try to be consistent in using "macOS" instead of "Mac" or "MacOS". (See l.20, 32, etc)

darcywong00 · 2026-01-26T03:47:57Z

+
+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.


We can style "notes" like

Suggested change

Note that Keyman Developer is a separate app from Keyman, which is the app that lets you use any keyboard created with Keyman Developer.

> [!Note]

> Keyman Developer is a separate app from Keyman, which is the app that lets you use any keyboard created with Keyman Developer.

and would look like

When the text came out of Notion, some of the notes were marked with HTML, others with the >, but then the links that were in those paragraphs didn't work, so I ended up removing the markup for notes and tips. My preference would be to wait on adding markup to style the notes.

Yes, let's worry about integration before minor styling details

fair enough. I was just looking to have consistency in the styling across the site. But yeah can focus on content now

darcywong00 · 2026-01-26T03:58:51Z

+title: Introduction
+---
+
+[Next: Part 1 - Creating a Keyboard Project →](01-creating-keyboard-project)


The knowledge-base folder uses < and > for navigation arrows.
We probably don't want to implement a separate .php file

https://github.com/keymanapp/help.keyman.com/blob/29cf16f40ab32e3e37446de1ca0ef63a739fe116/knowledge-base/index.php#L51-L53

but for now maybe we just replace the arrows →?

I think the arrows here are nicer than the ones in the KB and I am not sure why we would be worrying about this anyway @darcywong00?

Original author used the arrows. I've changed them to wedges.

darcywong00 · 2026-01-26T04:03:17Z

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


Should we make all the help.keyman.com links relative?

like
/developer/download

and all the
/developer/17.0/
/developer/18.0/ links become

/developer/current-version/

This is not a relative link. But relative links on help.keyman.com are a good idea with /developer/current-version in order to avoid linking people into old content (and it also means if content shifts around, we will be prompted to update the tutorial accordingly).

I tried to follow @mcdurdin 's advice on links, but could easily have goofed it up!

in response to Darcy's suggestion Co-authored-by: Darcy Wong <darcy_wong@sil.org>

Co-authored-by: Darcy Wong <darcy_wong@sil.org>

mcdurdin

Moved TODO to top comment for visibility

DavidLRowe · 2026-02-24T00:57:07Z

@mcdurdin What's the status on this PR? Do I need to make some changes?

mcdurdin · 2026-02-24T09:17:46Z

@mcdurdin What's the status on this PR? Do I need to make some changes?

#15595 has some changes that would be good for you to look at.

Then I think I need to work through the first 3 TODO items in #15447 (review) before we can merge this.

docs: feedback for walkthrough

mcdurdin · 2026-03-05T12:41:19Z

I have consolidated the TODO list in the PR description

Remove old content and place redirects where the content is adequately replaced by the new walkthrough. Leaves some content which does not overlap the walkthrough. Moved reference information about package contents. Test-bot: skip

Test-bot: skip

Test-bot: skip Build-bot: skip

Co-authored-by: Eberhard Beilharz <ermshiperete@users.noreply.github.com>

docs: remove old content that is deprecated by walkthrough

docs: move walkthrough up one level

docs: tweak walkthrough content

DavidLRowe added 2 commits January 15, 2026 19:45

Update index.md to include walkthrough

0844780

Add files for walkthrough tutorial

441a385

github-project-automation Bot moved this to Todo in Keyman Jan 16, 2026

github-project-automation Bot added this to Keyman Jan 16, 2026

github-actions Bot added the developer/ label Jan 16, 2026

keymanapp-test-bot Bot added the user-test-missing User tests have not yet been defined for the PR label Jan 16, 2026

keymanapp-test-bot Bot added this to the A19S20 milestone Jan 16, 2026

keymanapp-test-bot Bot removed the user-test-missing User tests have not yet been defined for the PR label Jan 16, 2026

DavidLRowe requested a review from darcywong00 January 16, 2026 04:50

darcywong00 changed the title ~~Walkthrough tutorial~~ docs(developer): Add Developer walkthrough tutorial Jan 16, 2026

keyman-server modified the milestones: A19S20, A19S21 Jan 16, 2026

darcywong00 mentioned this pull request Jan 19, 2026

docs: keyboard tutorial keymanapp/help.keyman.com#2024

Open

darcywong00 reviewed Jan 26, 2026

View reviewed changes

keyman-server modified the milestones: A19S21, A19S22 Jan 31, 2026

Merge branch 'master' into walkthrough

13626ff

github-actions Bot added the docs label Feb 2, 2026

add TOC link

8f36d07

in response to Darcy's suggestion Co-authored-by: Darcy Wong <darcy_wong@sil.org>

github-actions Bot added docs and removed docs labels Feb 2, 2026

update arrows and macOS references

aa6f6d2

github-actions Bot added docs and removed docs labels Feb 2, 2026

update macOS references in glossary

0373122

github-actions Bot added docs and removed docs labels Feb 2, 2026

docs(developer): address review comments on walkthrough

1207a01

Co-authored-by: Darcy Wong <darcy_wong@sil.org>

mcdurdin reviewed Feb 18, 2026

View reviewed changes

keyman-server modified the milestones: A19S23, A19S24 Feb 27, 2026

Merge pull request #15595 from keymanapp/walkthrough-feedback

4abe55c

docs: feedback for walkthrough

github-actions Bot added docs and removed docs labels Mar 5, 2026

mcdurdin and others added 6 commits March 9, 2026 15:04

docs: move walkthrough up one level

82e7804

Test-bot: skip

docs: tweak walkthrough content

6872e94

Test-bot: skip Build-bot: skip

docs: address review comments

0a89686

Co-authored-by: Eberhard Beilharz <ermshiperete@users.noreply.github.com>

Merge pull request #15710 from keymanapp/walkthrough-remove-old-content

fb3cf3f

docs: remove old content that is deprecated by walkthrough

Merge pull request #15711 from keymanapp/walkthrough-move-folder

8beac6e

docs: move walkthrough up one level

github-actions Bot added docs and removed docs labels Mar 13, 2026

Merge pull request #15712 from keymanapp/walkthrough-content

d09f0ec

docs: tweak walkthrough content

github-actions Bot added the docs label Mar 13, 2026

mcdurdin approved these changes Mar 13, 2026

View reviewed changes

github-actions Bot added docs and removed docs labels Mar 13, 2026

keyman-server modified the milestones: A19S24, A19S25 Mar 14, 2026

mcdurdin merged commit a6225bf into master Mar 16, 2026
6 checks passed

mcdurdin deleted the walkthrough branch March 16, 2026 03:54

github-project-automation Bot moved this from Todo to Done in Keyman Mar 16, 2026

mcdurdin mentioned this pull request Apr 8, 2026

docs: Import Keyman Developer tutorials from Notion keymanapp/help.keyman.com#1542

Closed


		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.

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


		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.

	Note that Keyman Developer is a separate app from Keyman, which is the app that lets you use any keyboard created with Keyman Developer.
	> [!Note]
	> Keyman Developer is a separate app from Keyman, which is the app that lets you use any keyboard created with Keyman Developer.


		### Installing Keyman Developer

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

Uh oh!

Conversation

DavidLRowe commented Jan 16, 2026 • edited by mcdurdin Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Interpreting Errors

Uh oh!

keymanapp-test-bot Bot commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User Test Results

Uh oh!

DavidLRowe commented Jan 16, 2026

Uh oh!

darcywong00 commented Jan 16, 2026

Uh oh!

darcywong00 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcdurdin left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DavidLRowe commented Feb 24, 2026

Uh oh!

mcdurdin commented Feb 24, 2026

Uh oh!

mcdurdin commented Mar 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

DavidLRowe commented Jan 16, 2026 •

edited by mcdurdin

Loading

keymanapp-test-bot Bot commented Jan 16, 2026 •

edited

Loading

mcdurdin left a comment •

edited

Loading