[Bf-docboard] How to Achieve Better Search Results

[Campbell Barton]

Editing the manual to match the UI is fine in general, though this
shouldn't have to some big project.
Just correct when inconsistencies are found.

Such minor changes don't need to go via review, so we can give you
commit access for that.


While its good to point out issues and check on solutions (as you've
done). Issues like this shouldn't be blocking us from getting on with
generally improving the manual.

Once we're sure they are bugs, best report them up-stream and move on.
https://github.com/sphinx-doc/sphinx/issues

In this case the issue you've raised has similar reports, so looks
like its known pain-point:

- https://github.com/sphinx-doc/sphinx/issues/1341
- https://github.com/sphinx-doc/sphinx/issues/1486

reply to other details inline...

On Sat, Sep 19, 2015 at 2:42 PM, Ethos Erlanger
<ethos.erlanger at comcast.net> wrote:
> Two Examples of unfound Terms:
>
> Ico Sphere
>
> UV Sphere

Sphinx doesn't index 2 letter words, Noticed this is an issue searching for IK.
Even when changing to "Ico Sphere" doesn't work, that seems like a bug.

> Note that both "Ico Sphere" and UV Sphere are written as two words in the
> Blender Program, while the documented in the Reference Manual lists both
> terms as one word each  "IcoSphere" and "UVSphere".
>
> I could embark on a search for other un-found terms like this. When found,
> may I presume that this may be a simple matter of correcting the typing
> found in the Reference Manual and that I may proceed with an edit? Or would
> I break something fundamental about how the reference Manual is written if I
> were to jump in on edits of these types of inconsistencies?
>
> Another example of a two-word term that was problematic (in various ways)
> when searching for the term.
>
> "Apply Transform" or "Apply Modifier" --  I used these terms because I
> simply did not know that the full term is "Apply Object Modifier" or this is
> how I saw it or heard in a tutorial.
>
> The search for Apply Transform returns a section or topic of "Clear Object
> Transformation" and unless I read down to the second page of the entire
> topic, I would not expect the topic of "Apply Object Transformation" to be
> found under and subordinate to "Clear object Transformation". How can the
> "Findability" of these terms be improved?
>
> Please Note: This is not a gripe or a rant, but an earnest appeal to learn
> how I can help to edit or create documentation that is searchable.

Understood.
It seems these are known problems with sphinx's search.

> Ethos Erlanger
>
>
>
>
> On Sat, Sep 19, 2015 at 6:59 AM, Ethos Erlanger <ethos.erlanger at comcast.net>
> wrote:
>> I have been reading the current version of the Blender Reference
>> Manual, and while searching for information I am typing terms into the
>> search bar and getting no results.
>
> Can you give an example of a few terms that fail?
>
>> 1)    Is there a place to read how the search bar works?
>
> As far as I can see the docs don't go into details about implementation,
>
> Search the user archives:
> https://groups.google.com/forum/#!forum/sphinx-users
>
> In the source (search directory):
> https://github.com/sphinx-doc/sphinx/tree/master/sphinx
>
>> 2)    When I work on editing or writing a section that I would like to
>> contribute to, how would I establish keywords or search terms that I
>> believe users might typically enter into the search bar to find the
>> subject that I worked on?
>
> As far as I can see, this isn't supported.
> Worth asking about in sphinx-users group linked above.
>
>> Ethos Erlanger
>>
>>
>>
>>
>>
>>
>> _______________________________________________
>> Bf-docboard mailing list
>> Bf-docboard at blender.org
>> http://lists.blender.org/mailman/listinfo/bf-docboard
>>
>
>
>
> --
> - Campbell
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard



-- 
- Campbell