Quick-Start Documentation Updates - PurpleHullPeas rev1

[PurpleHullPeas]

I have a few suggestions for updating the Quick-Start Documentation based on some recurring questions in the Facebook Group and my experience making/updating tutorials to make them more noob-friendly. I would do the changes myself, but the Wiki is not open for editing and it appears that I cannot do a pull request for wiki updates (???).

-Add more direct links in the Quick-Start Guide to point to relevant topics.
Some users had trouble finding mpmd_marlin_1.1.x-uSDCard.zip, which I can understand. A note that it can be found near the bottom of the latest release page (hyperlinked), could be helpful here.
I realize that "Configuring a Print" is already linked, but I think adding a direct link to the Start/End Gcode could help drive the point home. I.E., 95% of the time anyone started to ask any questions about flashing MPMD Marlin 1.1.X or its predecessor, this would come up.
A reference to this issue within the "Calibrating the Printer" section may also be helpful.

-Firmware Flashing Details (including alternate method):
Here is a quick Google Doc I slapped together, which contains a method to flash the firmware via STLink. Feel free to link the document directly or extract the information as you see fit.
https://drive.google.com/file/d/1qK-VuOvtXk0OAKperCJYZGfuytqHtzNo/view?usp=sharing

-More emphasis on Start/End Gcode: I saw a lot of people simply using the same gcode from the built-in Cura definition. I'll copy-paste some suggested notes to add to the Start Gcode page.

Start Gcode Notes:

There are a few small, but notable, differences between the recommended Start Gcode for stock firmware versus MPMD Marlin 1.1.X

1. You should delete any configuration lines (M92, M665, M666, M301, M304, M500, etc.) from your Start Gcode, because they could interfere with other values calibrated earlier in the Quick-Start Guide. I.E., it is recommended that you store your configuration values to EEPROM.

2. Your z-offset was set earlier using M851 in the "Calibrating the Printer" section of the Quick-Start Guide. Return to that section if you need to adjust it.

3. G29 does not work the same way as stock firmware. Your MPMD Marlin 1.1.X G29 line should just read "G29 P0" (see the examples) to do a single probe using the stored mesh from the "Calibrating the Printer" section of the Quick-Start Guide. Just running "G29" will redo the entire 7x7 bed at the default 55 mm probe radius.

[aegean-odyssey]

Thanks. I do want to improve the documentation, so your observations and comments are helpful. While git is not new to me, creating and maintaining a GitHub project is. The wiki is ok, but as you point out it has its limits. I took a stab at using GitHub's Pages web hosting for one of the repositories, and it seems to work. So, I think I may move the wiki content into a separate project repository, so things like a pull request, separate branches, etc. are readily available.

[aegean-odyssey]

I've incorporated your suggestions into the wiki page -- good suggestions. Sadly my wiki page is filled with information, but light on being useful -- structure and organization problems, I believe. Now that content is collecting in the wiki pages, it's probably time for a documentation overhaul and a re-think on making the wiki content more purposeful.

[aegean-odyssey]

@PurpleHullPeas, in a calmer, take a step back moment I clicked on the "Quick Start" link -- your critique is dead-on, and I think my "band-aid" attempts to fix the issue(s) actually make things worse.

So I'm in the "spit-balling" phase of a plan to overhaul the Quick Start information specifically and all of the documentation generally. To this end I'm thinking:

• converting the wiki into a full-fledged repository OR moving all of the documentation to a "docs" folder in the mpmd_marlin_1.1.x repository -- either choice allows for "git pull" contributions and the automatic generation of an mpmd_marlin_1.1.x firmware (documentation) web site;

• creating an easy to find FAQ;

• changing the structure of the "Quick Start" -- adding a "Where to get help" section at the top, followed by more succint installation instructions with commentary more focused on answering questions that may pop up during the installation (your suggestion);

• changing the name of the mpmd_marlin_1.1.x-uSDCard.zip file, so that it displays at the top of the release page's list of assets -- it's not possible to generically link to the "latest" version of any of the asset files (just the release page as a whole), so this is a bit of a compromise;

• with documentation being "compiled" to a web site, it may be possible to maintain direct links to the actual latest firmware files and the zip file, overcoming the limitation in the previous item;

• also place the individual firmware files (the variants) in a folder in the zip file -- grabbing the zip file will then be the only required download, so perhaps "Quick Start's" step 1 could feel simpler (i.e. download this file...);

• adding firmware release notes with a "who should upgrade" or "why upgrade" (or maybe adopt a better format for the actual git hub release page);

• in the documentation, capture a distillation (some how) of some of the on-going discussions (for example, the issues labeled "documentation") to retain the contributors own words and to capture the "flow" of the discourse.

That's it so far. Again mulling things over, planning.

Thoughts and suggestions welcomed.

[PurpleHullPeas]

Thanks for updating it. My ultimate goal is to be able to simply point someone to the Quick-Start Guide, without any additional commentary, whenever someone asks about flashing MPMD Marlin 1.1.X. I maintain a calibration guide document and frequently answer questions in the Facebook Group. Questions appear less-frequently on Reddit, but I try to answer questions there, too. Many of the questions that pop up are super repetitive and also involved enough that I don't want to type things out over-and-over again. However, when I can simply post a screenshot or a link, helping others becomes much easier.

Additional Notes:

I was under the impression that the following link would always go to the latest release:
https://github.com/aegean-odyssey/mpmd_marlin_1.1.x/releases/latest

CALIBRATE_25MM.gcode is a nice addition. I feel like extra attention may need to be called towards it in the Quick-Start Guide, but perhaps a well-organized FAQ is a better answer. This is certainly a recurring question in the Facebook Group.

Thanks for your work. Take whatever approach you want to document your firmware. I've noticed that Marlin4MPMD's GitHub wiki is editable by pretty much anyone. I don't think that has ever been a problem for mcheah, but I understand if you want to maintain better control of the documentation.

[aegean-odyssey]

@PurpleHullPeas, I like your ideas. I have no particular insight into how to improve the documentation, only hunches. So, embarking on a documentation overhaul seems to me to be a "hit or miss" proposition. I think your idea of opening up the wiki has a much better chance of yielding better documentation. Yes, this a better approach.

I like the wiki (over git pages) because it doesn't require a development system; a web browser does just fine. And for documentation, the wiki's limitations (no theming, limited formatting options and markup, etc.) aren't really show-stoppers. Although, it does seem overly complicated to store images in the wiki repository.

I have to no problems making the wiki public -- it's a good idea. And I'm slightly embarassed that the solution didn't cross my mind. I do have one or two style guidelines, and I think we'll need one or two participation rules. I'll write them up, put them in the wiki, and then open the wiki up.

And, yes, you are correct:

I was under the impression that the following link would always go to the latest release:
https://github.com/aegean-odyssey/mpmd_marlin_1.1.x/releases/latest

I was hoping to generically point directly to the latest zip file with something like:
https://github.com/aegean-odyssey/mpmd_marlin_1.1.x/releases/latest/mpmd_marlin_1.1.x-uSDCard.zip, but the release tag (e.g. 119r12) is needed to get to the "assets" directly.

[aegean-odyssey]

@PurpleHullPeas, the wiki should now be editable to all GitHub users. I posted a few "rules" but I really have only two concerns: that we are disciplined about the name of the project, and that the participants respect each other. I don't see either as a problem.

You have a much better vision than I of how this documentation should serve its audience. So, please, have at it. Feel free to change the structure and organization as you see fit. I will probably be asking a lot of "why" questions -- please, don't be put out. They're not a judgment, but rather the way I come to understand things.

[aegean-odyssey]

@PurpleHullPeas, I'm thinking of dropping all of the variants in the assets list of the next release. I've placed the variants in a folder, \firmware, on the SD card zip file instead. My thinking is that there will only be one file to download, mpmd_marlin_1.1.x-119r14-SDCard.zip, and that updated instructions would be overall a bit simpler and maybe less confusing with the change. Thoughts?

[mulcmu]

Consolidated into one zip to download seems like a good idea for the releases. I'd restructure zip so that there is one folder in the zip to copy to the SD card. This would minimize unnecessary folders and files on the SD card that could lead to confusion. I have been putting all the M851 setup files in a subfolder to save some button presses on the LCD.

Proposed Zip Structure

[PurpleHullPeas]

@aegean-odyssey @mulcmu I like both of these suggestions. Admittedly, I have been doing all of my calibrating/printing directly over Octopi or Python, so my input here is based purely on guessing what might make it easier for newcomers.

[aegean-odyssey]

Thank you, both!

@mulcmu, I think I see what you're getting at with the structure. The zip file is intended to be the entrie micro SD card contents -- the printer's firmware ignores all files but directories and g-code files, so I don't think there is problem with a simple installation instruction like "copy the entire contents to the root directory of the micro SD card". I really like the M851 folder idea. Besides fewer button presses, I think it can help (eventual) documentation focus attention on the one calibration step that is machine-to-machine specific, setting the offset; brilliant. And I noticed the checksum file; another good idea. I've incorporated both ideas into the next firmware release, r14.

@PurpleHullPeas, are you considering turning your python script into an OctoPrint-plugin? Interesting possibility.

[PurpleHullPeas]

@aegean-odyssey Nope. My understanding is that if Issue #25 gets added, then there will be no need for my script anymore. It could all be replaced with simple gcode files.

[aegean-odyssey]

My goal is to get a very good automatic calibration out of the G33 code; and I'm still mulling over how the "calibration duties" get distributed among the G33 and G29 codes; AND I have to keep an eye on the program space limitations. I'm pretty sure, though, that however it turns out, it won't be the definitive answer to calibrating the MP Mini Delta printer -- there will always be alternate methods, objectives, and desires.

There is a certain elegance to an external calibration tool like your script. It's scope is rather focused, but at the same time, it is open-ended along the proper lines to accommodate alternate methods, objectives, and desires. It's a solution that fits the nature of the problem well.