Skip to content

Comments

docs: feedback for walkthrough#15595

Open
mcdurdin wants to merge 2 commits intowalkthroughfrom
walkthrough-feedback
Open

docs: feedback for walkthrough#15595
mcdurdin wants to merge 2 commits intowalkthroughfrom
walkthrough-feedback

Conversation

@mcdurdin
Copy link
Member

Presenting as a commit as I made many minor edits in-place and this was much simpler than trying to use GitHub review for this level of detail.

Additional notes:

Notes on tutorial

It belongs at the samw level as the 'Keyman Developer Guides' topic /guides/walkthrough, rather than guides/develop/walkthrough

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:"

  • We want to eliminate the other tutorials over time, so we should avoid referencing them

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:

  • This is a little confusing, perhaps avoid discussion of mnemonic layouts at this point, and just say that the 'e' matches the key cap of the K_E key, or something like that?

04-using-debugger

Interpreting Errors

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

Test-bot: skip
Build-bot: skip

Presenting as a commit as I made many minor edits in-place and this was
much simpler than trying to use GitHub review for this level of detail.

Test-bot: skip
Build-bot: skip
@keymanapp-test-bot
Copy link

User Test Results

Test specification and instructions

User tests are not required

Copy link
Member Author

@mcdurdin mcdurdin left a comment

Choose a reason for hiding this comment

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

The walkthrough is looking really good. I made a few editorial edits but most of the changes were formatting and structure related.

Comment on lines +5 to 11
<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>

Copy link
Member Author

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

Comment on lines +81 to +82
> [!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.
Copy link
Member Author

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

## Reference

See [https://help.keyman.com/developer/current-version/context/keyboard-editor#toc-touch-layout-tab](https://help.keyman.com/developer/current-version/context/keyboard-editor#toc-touch-layout-tab) for more details.
See [Touch layout editor documentation](../../../context/keyboard-editor#toc-touch-layout-tab) for more details.
Copy link
Member Author

Choose a reason for hiding this comment

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

I've used relative links where the content is stored in current-version/ as this will keep the reader in the same version of content.

Copy link
Member Author

Choose a reason for hiding this comment

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

This file sorts the navigation on the left hand side in the same order as the tutorial, rather than alphabetically by title

Copy link
Member Author

Choose a reason for hiding this comment

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

Image was too large and added horizontal scrollbar

Copy link
Contributor

@darcywong00 darcywong00 left a comment

Choose a reason for hiding this comment

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

lgtm

I find the navigation clearer now

@@ -1,10 +1,11 @@
# Using the Debugger
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
# Using the Debugger
---
title: Using the Debugger
---

The title was showing up twice

Image

Follow the instructions at [https://help.keyman.com/developer/keyboards/](https://help.keyman.com/developer/keyboards/) to submit your keyboard to the Keyman keyboards repository. This will enable anyone with Internet access to download and use the keyboard. (Please do not submit the Dagbani keyboard used in the Step-by-Step tutorial. There is already a Dagbani keyboard in the repository.)
Follow the instructions at [Working with the Keyman Cloud Keyboard Repository](https://help.keyman.com/developer/keyboards/) to submit your keyboard to the Keyman keyboards repository. This will enable anyone with Internet access to download and use the keyboard. (Please do not submit the Dagbani keyboard used in the Step-by-Step tutorial. There is already a Dagbani keyboard in the repository.)

One requirement for keyboards that are submitted to the Keyman keyboards repository is the addition of a PHP help file that provides the online help available on the keyman.com site. See the **Editing the PHP help file** section of the [Writing Keyboard Documentation](07-writing-keyboard-documentation) page for more details.
Copy link
Contributor

Choose a reason for hiding this comment

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

How about using the link to the "Editing the PHP help file" section?

Suggested change
One requirement for keyboards that are submitted to the Keyman keyboards repository is the addition of a PHP help file that provides the online help available on the keyman.com site. See the **Editing the PHP help file** section of the [Writing Keyboard Documentation](07-writing-keyboard-documentation) page for more details.
One requirement for keyboards that are submitted to the Keyman keyboards repository is the addition of a PHP help file that provides the online help available on the keyman.com site. See the **Editing the PHP help file** section of the [Writing Keyboard Documentation](07-writing-keyboard-documentation#toc-editing-the-php-help-file) page for more details.

- Click on the **dag-short-wl.txt** filename just below this paragraph to open the file (or right-click and select Open in a new tab).

[dag-short-wl.txt](./dag-short-wl.txt)
* [dag-short-wl.txt](./dag-short-wl.txt)
Copy link
Contributor

Choose a reason for hiding this comment

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

Do you want to also indent the Aduna_anndaaka.txt wordlist? (l. 268)

Co-authored-by: Darcy Wong <darcy_wong@sil.org>
@github-actions github-actions bot added docs and removed docs labels Feb 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

2 participants