Gcode documentation change

[droftarts]

Over time, the single Gcode reference page has become huge, and was causing slow loading times from both the server and with some clients. It was also becoming increasingly difficult to edit (you only get a small window to edit in) and to navigate the page (it's easy to get lost as you scroll).

Due to this, we have reorganised the Gcode page to have links to individual pages for each Gcode. It still has a heading for each Gcode, and a short description. The heading means that all old links to the Gcode dictionary should still work, though take you to the short entry with a link to the individual page, eg https://duet3d.dozuki.com/Wiki/Gcode#Section_M584_Set_drive_mapping. You can, of course, link directly to a page, for example https://duet3d.dozuki.com/Wiki/M584. This will also allow us to put more detail in for each Gcode.

Another advantage is that it should be easier to have a Gcode highlighter/lookup in DWC now, something similar to what @theKM did recently in this thread https://forum.duet3d.com/topic/24970/handy-way-to-browse-gcode-docco-directly-from-the-gcode

There's also an updated 'Gcode by function' page, here: https://duet3d.dozuki.com/Wiki/GCodes_index_by_function

If there's any issues with this change, or suggestions for improvement, please post here.

Ian

[alankilian]

@droftarts

The only downside I can think of is sometimes I would use the browser search feature to look for an "M" code and find not only the description for that code, but additional code that are used in conjunction and that was helpful.

It may be that the short descriptions also contain the "M" code reverence, so it might be just fine. (Of course, I can't think of an example where there was a benefit for this feature to test it out.)

I do see the major advantages you mentioned, so I'm not suggesting going back.

[droftarts]

@alankilian said in Gcode documentation change:

The only downside I can think of is sometimes I would use the browser search feature to look for an "M" code and find not only the description for that code, but additional code that are used in conjunction and that was helpful.

It may be that the short descriptions also contain the "M" code reverence, so it might be just fine. (Of course, I can't think of an example where there was a benefit for this feature to test it out.)

Yes, I searched the Gcode in much the same way. I've tried to write the short summaries so that they will pick up relevant searches, and also the Gcodes by function page categorises related Gcodes together. Happy to entertain amendments to either! Also can expand the individual Gcode pages to include 'related' Gcodes.

I've added 'or suggestions for improvement' to my original post!

Ian

[alankilian]

@droftarts

By the way, I only have FIVE top-level bookmarks in my browser's always-displayed toolbar (and several folders of bookmarks) and your GCODE page rates one of the coveted spots. (Right next to the Massachusetts COVID dashboard, I'm sorry)

So thank you for the effort. This is an awesome resource.

[droftarts]

@alankilian said in Gcode documentation change:

I only have FIVE top-level bookmarks in my browser's always-displayed toolbar (and several folders of bookmarks) and your GCODE page rates one of the coveted spots.

Honoured! Humbled!

Ian

[sinned6915]

Honestly, I think its counter-productive and now HARDER to use. I agree the old way was not efficient, but this is now just plain aggravating.

Most often, I am going to look for one of the options or modifier to a gcode and now its takes 2 or even 3 clicks to find it.

Was the old page huge, yes it was. Unmanaglebal from the the users's perspective: not al all. Cntl-F is your friend. Making it easier to edit and code from the back end- that sounds like a developer's issue to be solved and should not be done at the expense of the user experience.

I was going to see what the effect of this change was on the gcode lookup from DWC interface.... that is gone now? When/where did THAT go? Wasn't the search field at the top of the main page gcode lookup?

As a comparison- look at Marlin's docs. https://marlinfw.org/meta/gcode/
Its easy to navigate, its color highlighted, its fast and responsive.
Click on a link in the left frame, it takes you to the detailed page.
Scroll on the right frame, click on a link, it takes you to the detailed page.
Maybe this is the happy medium compromised ?

The target for function should be the lowest common denominator, the novice user in front of their computer not some pie-eyed wish of a function down the road for DWC.

How many previously cited links just got broken by this change in format? If you are looking at an old post in the forums, will it still work?
NONE! All those old links are broken now

[achrn]

@sinned6915 said in Gcode documentation change:

Honestly, I think its counter-productive and now HARDER to use. I agree the old way was not efficient, but this is now just plain aggravating.

Well, I like the new layout a lot.

As a comparison- look at Marlin's docs. https://marlinfw.org/meta/gcode/
Its easy to navigate, its color highlighted, its fast and responsive.
Click on a link in the left frame, it takes you to the detailed page.
Scroll on the right frame, click on a link, it takes you to the detailed page.

I'm really struggling to see how this is very different to how the new duet3d page is arranged.
https://duet3d.dozuki.com/Wiki/Gcode
Click on a link in the left frame, it takes you to the one-line summary.
Scroll on the right frame, click on a link, it takes you to the detailed page.

Other than that the Marlin page links are dark reddish and the Duet pages are dark bluish-grey, I'm struggling to see any significant difference. Can you elaborate?

The Duet page has a longer introduction than the Marlin - but the old page had that.

I think links in old forum posts still work. For example: https://forum.duet3d.com/post/104964

[gloomyandy]

@achrn I guess the main difference from Marlin is that clicking on items in the left panel takes you to the detailed page in Marlin, with RRF it takes you to the summary. Marlin also keeps the left hand pane in place when displaying the detailed page (which I think is probably better). I think that the Marlin way may be more what most people would expect. Not sure if these differences are there for a good reason (allowing old links to still work?).

Personally I actually preferred the old one big page setup, but then I'm a search sort of guy....

[achrn]

@gloomyandy said in Gcode documentation change:

Personally I actually preferred the old one big page setup, but then I'm a search sort of guy....

Now you can drop (say) M586 in the top banner search box at https://duet3d.dozuki.com/ and top hit takes you straight to the detail - so it's a single search rather than a search, open the hit (the 'dictionary' page) and need to do another search within the page. That, I think, is what I'm liking most about the new arrangement - I seem to get where I'm going more directly with one search.

[gloomyandy]

@achrn Yes but I very rarely know what the gcode command is that I want. But I know what it is I want to do and can usually find the command pretty quickly with just simple text searches.

[royal32]

Hi All-

This is an interesting topic- I understand and agree with the reasoning behind the change, but I've got to say that it's pretty frustrating to use now after trying to get used to it for a few days.

Edit: it seems to me that the reasonings behind the change make sense on the surface, but are actually made worse by the change...

I Ctrl-F'd my way around the page very easily using keywords I thought would be in the documentation for the gcode i was looking for, and IMO the search feature at the top (which disappears if you aren't at the very top...) is not a suitable alternative to being able to search within the monolithic document. You also lose the ability to freely scroll around to look at adjacent and possibly related gcodes.

I used to be able to keep the Gcode page pinned in my tabs, a single resource while I'm working, now I have to think a lot harder about what keywords I should look for that would fit in a single sentence summary of that gcode, then open it in a new tab once I find it. That all involves more tab identification and switching, more clicking around, more load times... its just overall clunkier.

I see others talking about the marlin documentation, personally i'm not a fan of that either, but one improvement i'd take from that is keeping the sidebar index on the page when you're viewing the documentation of a single gcode. I'm not sure if thats possible with how you have it set up on dozuki. The individual pages feel completely disconnected and isolated from every other gcode, even related ones, as well as from the index itself.

Unfortunately I'm not sure what a good middleground solution would be between ease of page development and user experience that fits within dozuki's structure and technical limits, im not familiar with the platform. As far as slow loading times, I always thought the loading time of the monolithic page was very reasonable, I never gave it a second thought. Having to load new pages for every entry i click on though i am definitely noticing.
As far as serverside performance, that seems like an issue to be solved another way, its just text. Forgive me as I haven't touched web dev in years but shouldn't serverside caching take care of that?

Either way, measurement with brower cache disabled of the old page's loading time/size vs the current one demonstrates a noticeable difference for sure, but IMO not a worthwhile one. I might be in the minority not noticing another second when I open the wonderful compendium that is the RRF Gcode Dictionary. And with browser caching its less than that.

Side note, a gcode lookup in DWC like you mentioned sounds amazing.

Seth

[theKM]

...for people that would rather one massive page, we could write a script that would compile it all into a single page like it used to be

[droftarts]

Thanks all for your feedback, I understand that this change to the documentation isn't necessarily welcomed by all, and I'll strive to improve it.

There are a couple of reasons for the new structure of the pages, and limitations to what we can do:

1. To maintain existing links (yes, they should all still work), the headings have to be shown in the new page, as they appeared in the old page, without a link in them. This lead to the layout with the link to the individual page and description on another line.
2. Current descriptions of Gcodes were a quick, rough, first pass. Suggestions (or better still, edit the wiki) for improvements greatly received.
3. Dozuki can only show the Table of Contents for the current page (ie, the headings) in the sidebar; it can't show a list of pages. There's also no global or sectional navigation option.
4. Afaik, there's no way to inject html into a Dozuki page, so we can't do anything custom within the Dozuki system.
5. The Dozuki search system is out of our control, too.

Unfortunately, we can't go back to the single page, so we need to work with what we've got. For now, it would be really useful if people could show what searches they are doing, so we can improve the descriptions. To help this, here is an html document of the old page: Gcode - Duet3D.html.txt (download it and delete the .txt on the end of the file name, then it should open in your browser). If you could report what searches work in the old page, and don't on the new page, or what you would like to work on the new page, that would be very helpful.

Ian

[zapta]

@alankilian said in Gcode documentation change:

@droftarts

The only downside I can think of is sometimes I would use the browser search feature to look for an "M"...

Another one is that now we need to clIck twice to get to the information. The short summary is insufficient to understand the command.

Sometimes changes are helpful for the users and sometimes not

[theKM]

@droftarts ...looks like admins have access to a "header html" ability?... if you can inject a script tag in to the head, a lot could be done from that without the server's help.

[droftarts]

@thekm said in Gcode documentation change:

@droftarts ...looks like admins have access to a "header html" ability?... if you can inject a script tag in to the head, a lot could be done from that without the server's help.

Had a look, but I think that's the header for the whole site: https://dozuki.dozuki.com/c/Customization_and_Appearance#Section_Customization

Ian

[theKM]

@droftarts ...yup, it is the header for the whole site, but the script can first look at the current URL, and if it's on the page it wants, then it can hack it up, and if it's on some other part of the site it doesn't do anything.

[droftarts]

@zapta said in Gcode documentation change:

The short summary is insufficient to understand the command.

We can't put all the information about a Gcode in the short summary, otherwise we end up back at a long page. If you can cite specific examples, then I can update the summary.

Ian

[droftarts]

@thekm said in Gcode documentation change:

@droftarts ...yup, it is the header for the whole site, but the script can first look at the current URL, and if it's on the page it wants, then it can hack it up, and if it's on some other part of the site it doesn't do anything.

Ah, I see, thanks! Editing the site headers and footers is something only the site Admin can do, which is @T3P3Tony. I'll ask him if he wants to look into doing this. Unfortunately I'm no programmer or web developer, so it's not something I can do!

Ian

[T3P3Tony]

@theKM what script are you suggesting to insert?