Wikibooks search fails to find minkowski about openscad HOT 15 OPEN

Can you please elaborate on what you expect the OpenSCAD team to do here? We have no control over how the Wikibooks search works, so I don't see any possible action on our side other than fully moving away from Wikibooks (which has been discussed but would be quite some effort).

from openscad.

https://en.wikibooks.org/wiki/Special:Search?fulltext=Search+this+book&fulltext=Search&prefix=OpenSCAD+User+Manual%2F&search=minkowski&ns0=1&ns4=1&ns102=1&ns110=1&ns112=1

There is a search input field top right above the logo https://en.wikibooks.org/wiki/OpenSCAD_User_Manual

also https://openscad.org/cheatsheet/ will help you find things

from openscad.

from openscad.

from openscad.

I think the brackets confused the search. Putting just minkowski in the "search this book" box works for me.

from openscad.

It will find the section on the printed version
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version#The_OpenSCAD_Language_Reference
It also finds the links to https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations#minkowski ,
But the content of https://en.wikibooks.org/wiki/OpenSCAD_User_Manual itself is not searched.

So all information is found - but not every mention of the link.

from openscad.

from openscad.

I don't think I would call it "OK", but rather, it seems to me out of scope to even try to address search results. Integrated wiki search bars have been relatively poor quality in their search results since the dawn of wikipedia, and functionally we use wikibooks more as a convenient shared-editing host of our manual and tutorial content. For making content language findable, our prepared solution which I think is prominently linked in our documentation and tutorials, is the cheatsheet: https://openscad.org/cheatsheet/ This beats search bars by leaps and bounds, I think. Now if we did an inadequate job of making the cheatsheet clearly findable for new people, or in making its specific use or value clear, that I would consider worth doing a tweak if there is someplace more appropriate or useful to link to it, or a different way to describe it while doing so.

from openscad.

The problem with @JamesC1's second search is that it searches for "language reference", a phrase that appears in only a few places. (But the search doesn't find the top-level page, which seems pretty wrong.) The various "reference" pages don't have the word "reference" on them.

The biggest problem is, I think, that the "language reference" section looks sort of book-like. A few ideas for reducing the opportunity for confusion:

• We could change the name of the "OpenSCAD User Manual" section to something else that clarifies that it's a section of the larger manual. "Tutorial" comes to mind, but really only applies to a few of its subsections - and there's also the separate "OpenSCAD Tutorial" wikibook. "Overview" also comes to mind, but again a lot of its content is detail, not overview.
• Remove the "User Manual" section header, and maybe demote "Language Reference" to being a chapter.
• Remove "The OpenSCAD" from the titles of those top-level sections, which might make it less likely that a reader will think of them as books.

I thought about moving the language reference to a separate wikibook, but that would make the search picture worse.

from openscad.

from openscad.

The problem with splitting into two books is that then you couldn't hit both books with one search, except by doing a Wikibooks-wide search and trying to narrow it enough with keywords.

I think the better approach is to have one book - maybe even pulling in the currently-separate Tutorial book - and structuring it so that it's clear that that's how it's been done.

from openscad.

from openscad.

There's no law that says that the "user manual" can't have a reference section, so that particular aspect doesn't concern me. We'd have to change the text inside to avoid drawing that distinction. But since we don't publish anything other than a user manual, we could just drop the word "user".

I don't know Wikibooks well enough to know whether we can add hierarchy. But we can certainly put the word "reference" in appropriate titles.

from openscad.

Essentially there is one book with 2 major sections. To me it seems like the discussion is focusing on the wrong things.

Goto main book page: https://en.wikibooks.org/wiki/OpenSCAD_User_Manual

Use the appropriate search:

Select Search this book and find a reasonable list of hits in the OpenSCAD Book only:

Notably that finds exactly the minkowski entry on the Transformations page mentioned in the original post as first hit.

The only action I can see here is to make that search field a bit more obvious and (if that works) adding external pointers directly to this. Maybe even have an additional "search" page with an explanation of the search behavior if someone feels like writing that.

from openscad.

The manual, titled "OpenSCAD User Manual", has two distinct sections, titled "The OpenSCAD User Manual" and "The OpenSCAD Language Reference". I think his concern is that he was trying to find reference information, and all of the search results say "OpenSCAD User Manual" - the first section - and none of them say "OpenSCAD Language Reference".

That first link does lead to the reference section, but it isn't instantly obvious that it does, and one might reasonably think that it leads to the first section instead. (And to confuse the issue further, the last link, which also could be construed to lead to the first section, leads to a single-page "printable" version of the second section.)

The problem is that "OpenSCAD User Manual" refers to both the book as a whole, and to the first section of that book.

from openscad.