search

keymanapp / help.keyman.com

https://help.keyman.com/ source
9 stars 30 forks source link

docs: Import Keyman Developer tutorials from Notion #1542

Open darcywong00 opened 2 months ago

darcywong00 commented 2 months ago

@sku21 spent an internship revamping the keyboard development guides.

The content at https://www.notion.so/ltuse/Keyman-Developer-General-Tutorial-fb2b0b67f9014a66ae4e4b5b00a6198e

just needs to get exported to Markdown and incorporated in the guides here.

mcdurdin commented 2 months ago

Sadly, she ran out of time to complete the tutorial. We need to invest in finishing the tutorial first, before attempting to merge with content here. Once it is complete, I would like to deprecate and/or remove the existing tutorials, because I think what @sku21 has produced so far is going to be far more comprehensive and approachable than the outdated content we have here. But, all that to say, this needs to go on hold until the content is complete in Notion.

(FWIW, see also https://github.com/keymanapp/keyman/issues/12347 which means that the content will be merged into the keymanapp/keyman repo, not this one, when it does eventually land)

mcdurdin commented 5 days ago

Per FV team (@caforbes, @hopsandhops, @xyzhelen) feedback:

The Keyman Developer Documentation was difficult to reference. Most of the documentation is either for beginner users who will not be going into the code tab, or for people who know the program and Keyman’s language like the back of their hand. There is not much that helps a user bridge that gap. Or maybe part of the problem was in difficulties navigating the documentation and finding the correct page, etc. o It would be helpful if there were simple tutorials or explainers on the different files in a project, what they’re for, and/or where to edit them, for example.

and ...

I’ve attached a guide that we cobbled together internally – parts are specific to our workflow, but it might show the kind of information that we were looking for (mid-intermediate Keyman knowledge, no development background).

Copied to our Google drive (not public): https://drive.google.com/file/d/1-8QYkB_d8zeuJTVsNWQLQU0FurRn2paR/view?usp=drive_link

and ...

Add more information about all of the help and info files. Explain what does what, and what info is pulling from where

  • What does the help.htm do? It took more investigating that necessary to determine that this is for Web-Help, and so in our case is redundant since the base help is used on that page.
  • This specifically is not addressed in existing Keyman Developer tutorials – we were really confused about the help files.