You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Due to the move from monorepo machinekit/machinekit to separate repositories like machinekit/machinekit-hal, machinekit/EMCApplication, machinekit/mksocfpga (et cetera) most of the existing documentation in this repository is no longer current or even usable. This is causing problems for potential new users of the suite, because there is no other viable option for them to get at least basic familiarity other then reading the code or asking for help. (For example the machinekit/machinekit-hal#363 issue.)
The site structure itself is problematic and finding even documentation pages one knows exist is herculean effort. (My personal opinion and as stated to me during private conversations.) It's too deeply nested, the structure and logic is a relic from LinuxCNC days and the current theme has readability issues for such long documents.
Also, the build process depends on a Docker container with Jekyll and few additional packages from Michael Haberler based on Debian Jessie which is now _EOL_ed.
From this reason I propose creation of completely new site. Disregarding the current one. (Or maybe keeping it online at some secondary location with clearly stated note about the new one.)
The new site should have the following parts:
Landing page
Clearly stating that Machinekit organization has multiple projects (machinekit/machinekit-hal, machinekit/EMCApplication, machinekit/mksocfpga etc)
Something like the Moveit page, the ZeroMQ page or any other OSS page looking modern enough
Documentation
Quite minimal documentation set targeted at users to get them up to a middle level (not just There is halcmd command, but also nothing crazy)
One per project (machinekit/machinekit-hal, machinekit/EMCApplication, machinekit/mksocfpga etc)
Will live in this repository (i.e. no API documentation autogenerated from the source, only human written text)
Codelabs/Tutorials
Short howtos (under one hour) used to get the hands dirty quickly and take the user through one specific task
Content I presume to be added by the user themselves (i.e. not by developers) the most (The guy who just got the hang of it is the best one to teach the next person that same small step theory).
Organization section
Taken mostly from the current size
Information about the C4 process, the Machinekit organization, the communication channels etc
Technical proposition how to get it done quickly
(This is how I would have done it. If somebody who actually enjoys webdesign volunteers, then of course he will have the decision to make.)
The current workflow (one documentation repository, CI pipeline to run a static site generator and publish the built site to a second Github Pages repository) works, so keep it
Find some modern documentation tool for Jamstack (Jekyll, Hugo, Gatsby etc doesn't matter) which will support the landing page functionality, slap a Machinekit logo on it, change the colour palette to Machinekit one and be done with it
Use the Google Codelabs tools or just Hugo+Codelabs theme to create the Codelabs site as a separate site in this repository, put it under https://machinekit.io/tutorials address
Write the Github Actions workflow to rebuild the two to three sites ([Landing,] Documentations and Codelabs) on each push to this repository and push them to machinekit.github.io one
Keep it all simple and using preexisting tools, writing the text will be hard enough
The text was updated successfully, but these errors were encountered:
Due to the move from monorepo
machinekit/machinekit
to separate repositories likemachinekit/machinekit-hal
,machinekit/EMCApplication
,machinekit/mksocfpga
(et cetera) most of the existing documentation in this repository is no longer current or even usable. This is causing problems for potential new users of the suite, because there is no other viable option for them to get at least basic familiarity other then reading the code or asking for help. (For example the machinekit/machinekit-hal#363 issue.)The site structure itself is problematic and finding even documentation pages one knows exist is herculean effort. (My personal opinion and as stated to me during private conversations.) It's too deeply nested, the structure and logic is a relic from LinuxCNC days and the current theme has readability issues for such long documents.
Also, the build process depends on a Docker container with Jekyll and few additional packages from Michael Haberler based on Debian Jessie which is now _EOL_ed.
From this reason I propose creation of completely new site. Disregarding the current one. (Or maybe keeping it online at some secondary location with clearly stated note about the new one.)
The new site should have the following parts:
machinekit/machinekit-hal
,machinekit/EMCApplication
,machinekit/mksocfpga
etc)halcmd
command, but also nothing crazy)machinekit/machinekit-hal
,machinekit/EMCApplication
,machinekit/mksocfpga
etc)C4
process, the Machinekit organization, the communication channels etcTechnical proposition how to get it done quickly
(This is how I would have done it. If somebody who actually enjoys webdesign volunteers, then of course he will have the decision to make.)
https://machinekit.io/tutorials
addressmachinekit.github.io
oneThe text was updated successfully, but these errors were encountered: