Gcode documentation change

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:

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.
Current descriptions of Gcodes were a quick, rough, first pass. Suggestions (or better still, edit the wiki) for improvements greatly received.
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.
Afaik, there's no way to inject html into a Dozuki page, so we can't do anything custom within the Dozuki system.
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

royal32

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

You can access the last point in the page's history before it was broken up by adding ?revisionid=5349 to the url, like so:

https://duet3d.dozuki.com/Wiki/Gcode?revisionid=5349

I'll be using the locally downloaded version, but that bookmark will be useful if people need it on mobile devices etc while we figure out a good solution here.

Reviewing the initial reasoning for this change, I'm really not understanding any of them.
As far as slow loading times on either side... you've replaced a single page with all of the information on every gcode that measured 1.57mb (transferred/compressed) with a page of no information and just links that weighs 1.37mb, and every individual gcode page the user has to load weighs 1.34mb.
How does this change improve load times for either the server or the client, am I missing something? It seems to be significantly worse by my measurements. Am i fundamentally misunderstanding this?

As far as difficulty editing, If i were editing this I would prefer a monolithic document that i could Ctrl-F around in, rather than having to manage literally hundreds of individual pages. I managed a wordpress site for a few years, I would have lost my mind trying to do that. I can see that the editing window is very small, but you can Ctrl-A, paste it into something like vscode. It can fill up your whole screen, its color coded because vscode recognizes markdown, you get a minimap to help you navigate... thats how i would do it.

As far as getting lost while you scroll... i'm more concerned about getting lost in all of the different tabs i have open now with different gcodes. Yes it is a long document, but it is also very easy to search around and find what youre looking for between Ctrl-F and the index on the side.

Just my 2c.

Seth

zapta

@bot said in Gcode documentation change:

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

I rarely use the dozuki search because the results are kind of opaque and you need to enter each item to get an idea what is inside. Does it have a next-next mode where each click takes you to the page/location of next result?

This one provides more context but still not as functional as the one page search.

https://duckduckgo.com/?q=site%3Ahttps%3A%2F%2Fduet3d.dozuki.com+acceleration&atb=v88-4_g&ia=web