Gcode documentation change

[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?

[droftarts]

@thekm Thinking about it, I guess there are two options:

• a page that populates with all the individual pages (no idea how the ToC will render)
• a page that keeps the list of Gcodes in the ToC, and shows the content in the main frame

Is either of these something you could create a bit of code that we could test out? Or just a tiny bit of code that does something that we can test to see if the idea works at all?

Ian

[theKM]

@t3p3tony said in Gcode documentation change:

@theKM what script are you suggesting to insert?

It's not a script that is yet written, but it's a way to inject functionality into the page that people could optionally apply. For example, it could inject itself into the menu an option to have the page render like it used to (literally all the content on the one page), but the script could parse the links and fetch the content to inject into the page... along with any other fanciness that the script could do (previous script that I wrote cross-linked all the gcode references so that all gcodes were links people could navigate with).

[theKM]

@droftarts said in Gcode documentation change:

@thekm Thinking about it, I guess there are two options:

• a page that populates with all the individual pages (no idea how the ToC will render)
• a page that keeps the list of Gcodes in the ToC, and shows the content in the main frame

Is either of these something you could create a bit of code that we could test out? Or just a tiny bit of code that does something that we can test to see if the idea works at all?

Ian

...I'll look at poking the new page. The way the previous mega-page navigated with the cross-linking worked pretty nice for me, I'll see about making it run optionally (I think it'd be best if it didn't do anything until the user requested it to its dance, so inject a menu option for "mega page" in the top of the menu or something, that if clicked it'll transform the page).

[zapta]

@droftarts, looking for example, in this page, it has a link to M150. Should that link should go directly to the documentation of M150 where the various arguments are explained? This is probably the user intention in most cases they click on that link.

https://duet3d.dozuki.com/Wiki/Neopixel_and_DotStar_LEDs

In addition to that, the 'isolated' mode in each each operation is documented in an isolated page doesn't provide IMO as good user experience as the previous page . Kind of looking at the Mona Lisa through a keyhole. You can't search for topics that cross commands, related command are not visible (e.g. G90, G91).

I understand the need/desire to improve, and I understand that sometimes our muscle memory takes some time to adapt to changes, but this one feels as a regression functionality. This is not the end of the world, and we will 'survive' it but you may want to reconsider.

[droftarts]

@zapta Hardcoded links to the old page are throughout the documentation and forum. Providing a heading in the new page to act as a target for those links, with a longer summary and link to the full individual gcode entry underneath, is the best we can do at the moment. When/if we get around to updating all the links on Dozuki (not going to happen on the forum), they'll point at the individual page.

I understand everyone's reservations, I feel them too. We're looking at ways to improve searchability and visibility; it's early days. Unfortunately, we can't go back to the single page.

I would say that often when I do a ctrl-F search on the Gcode page, it's for something simple like 'stepper' or 'acceleration', and I barely look at the main frame; the highlights in the Table of Contents are enough to find what I'm looking for. If I can have some solid examples of searches that don't work on the new page, I can update the short descriptions, even if it's just to add 'Related: G91' to G90.

And don't forget the Gcode by function page! https://duet3d.dozuki.com/Wiki/GCodes_index_by_function

Ian

[zapta]

@droftarts said in Gcode documentation change:

we can't go back to the single page.

What was the problem with the old page, too large to load in a browser? What size was it? I guess that if it's technically 100% impossible (is it?) then there is not point in complaining

If I can have some solid examples of searches that don't work on the new page

Is the old page still exist somewhere so we can find examples that worked well there but not in the new model?

[T3P3Tony]

@droftarts said in Gcode documentation change:

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).

[zapta]

Thanks @t3p3tony. The file is less than 1M and downloaded quickly and loaded easily into my browser.

As an example, I tried a page search search for 'acceleration' and the new model didn't hit M593 and M669.

When you search the single page, you know that it will hit every mentioning of it. With the new summaries page, it will hit only if that page was manually curated properly, so it reduces the confident in the search.

(If there is a hard technical constraint that prohibits the single page than I understand, that's psychics and we just need to live with it, but if not, please reconsider).

[oozeBot]

We just talked about this in our standup and agreed that we'd rather it all be on a single page for many of the same reasons already listed. It's an invaluable resource..!

[bot]

For those worried about losing the searchability of a single page: have you tried using the dozuki search feature?

Searching for, as an example from this thread, "acceleration," finds all the appropriate pages, and more.

What is missing from the individual G-Code page listings, in the dozuki search results, is a description of the contents of the page. Not sure why that doesn't appear, but the search function works very well to find all the g-codes that reference acceleration.

https://duet3d.dozuki.com/Search?query=acceleration