Idea

A Kamphaus suggested Dec 1, '16 A Kamphaus commented Dec 6, '16

Updates to User Manual Search Capabilities

I would like to suggest some updates to the user manual. As a new user I refer to this often to remind myself of syntax or methodologies. But I seem to have the constant problem of searching for something that I think should be very easy to find only to have nothing returned or several things with titles that make it unclear which page is actually helpful.

Here is an example:

I would like to use an arrayed integer variable in my code. I am able to remember that this is call an intarray in FlexSim so I go to the user manual and look it up in the index. Why the index? Well because I expect something as ubiquitous as a variable type to have it's own entry. Here is what my index search returns:

Nothing.

Ok so that seems shortsighted but I can still do a "search". Here is why my search returns:

The correct answer here is "Writing Logic in FlexSim". Clicking on this brings me here:

Then to get to the topic I'm actually looking for I need to either search for "intarray" or trying clicking through the topics to find the thing that "search" found which made it believe this was relevant to my search text. In this example it is fairly obvious that the "Variable Types" is what I need.

So my first suggestion: when I click on this topic, the thing I was searching for could be highlighted or the window could jump right to the first instance of the thing I just searched.

Here is another example:

I would like to look up how to do a for loop in FlexSim syntax. Again I start with the index, "for loop" returns nothing, "loops" returns nothing, "loop" returns nothing. Ok so to the search..."for loop"

So again the one with the info I really want is "Writing Logic in FlexSim".

As for the top 2 results, I'm not really sure why they were returned. I clicked on both of these and did a find for "for loop" and the result was "Text Not Found". My suggestion here is to not return results that don't actually have the searched phrase in them.

I realize these are very simple concepts I'm searching for. I find it frustrating when it is not simple to find something that seems so basic and I would really like to see the indexing of the user manual and search capabilities improved to improve user experience.

users manual

indexsearch1.png (47.7 KiB)

search1.png (85.0 KiB)

writing-logic.png (129.7 KiB)

forloopsearch.png (197.7 KiB)

writing-logic.png (129.7 KiB)

· 2

A Kamphaus commented · Dec 01, 2016 at 06:05 PM

I'm not sure if this is the correct space to post this suggestion or not so please move if needed.

1 ·

Ben Wilson ♦♦ A Kamphaus commented · Dec 02, 2016 at 04:13 PM

@Anna Kamphaus, this was the perfect spot for your post. Good work!

Just in case the dev team all have their heads buried in their keyboards and don't see this idea (though they're usually pretty active here on the community), I've created an issue in their tracking software that references your post.

Thanks!

0 ·

Ben Wilson commented Dec 2, '16

@Anna Kamphaus, thanks for your detailed idea/request.

The dev team may address your request and give some ideas of what could be done in the software. In their defense, good search functionality is really, really hard to program. We have someone who worked for Yahoo at the time that Yahoo was pouring all of its capital and best employees into improving their search functionality... and failed!

Of course, the silver lining is that now that our manual is online (embedded here in this Answers forum), we can harness the power of Google's Pigeons to search for us.

As you can see in the animation above, by using "site:answers.flexsim.com" after your search query, you can limit Google's results to just our site. Not a perfect solution to your request, but hopefully something that can give you more mileage than you're currently getting with FlexSim's built-in user manual search.

Obviously we're a simulation company, and most of our development efforts are put towards improving the functionality of the software. Yes, the documentation is a paramount part of the experience, but because its not our bread-and-butter we've looked into outsourcing the organization/hosting/publishing to 3rd parties who specialize in this. This could be something that we'll see in a future release and would probably improve the sorts of problems you mention.

We are also working on a complete overhaul/rewrite to the user manual, which is going to be task-oriented and organized in a manner that is more logical, making it easier to find what you need by looking at the Table of Contents, not having to rely on search so much. Although it's going to be a long time before its complete (our current manual is more than 1500 printed pages!) we do have a full time technical writer working on it.

Also, dot syntax (coming with this month's release of FlexSim 2017) will hopefully make all aspects of coding more discoverable and easier to use and understand.

· 3

A Kamphaus commented · Dec 02, 2016 at 05:37 PM

I understand as a software company, documentation can often come secondary to making the software better overall.

Being able to search the answers site is great but can cause confusion. In my searches in the past I've landed in the 7.7 manual or the healthcare manual.

A "Search" is not usually my top choice when I'm looking for something and Table of Contents is a last resort because it is usually way too broad and not in alphabetical order. I see the Table of Contents, Index and Search as three distinct levels. The current TOC and Search are usable but the current index is almost non-functional. I do hope that you will be improving the index in the updated user manual.

2 ·

Joerg Vogel commented · Dec 02, 2016 at 04:41 PM

@Ben Wilson by voting your answer up I got an Internal Server Error.

0 ·

upvoting-internal-server-error.jpg (21.1 KiB)

Ben Wilson ♦♦ Joerg Vogel commented · Dec 02, 2016 at 05:18 PM

weird - well, its the thought that counts. Thanks!

0 ·

Matt Long commented Dec 5, '16

The old method for searching the user manual searched each page for the contained text and gave a whole slew of results that were not at all based upon relevance. We updated the search so it attempts to find and sort the pages based upon relevance. In order for this to work "really well", it requires additional data in each topic page to determine how that page's content compares to the other search results. Unfortunately, not enough time has been invested in completing that task so the search may not always give really good results. A main reason for this is as Ben said, we are completely rewriting the user manual. Any time spent modifying the current user manual beyond updating/adding information for new features and updates to the software, is really just wasted time.

When you search for "for loop", it's searching for pages that match both "for" and "loop", not for both words side by side. This could probably be improved.

As for searching for flexscript/coding/commands, the user manual's search is probably not the best place to be as it currently stands. We are working to improve the flexscript documentation as we move into dot syntax for version 2017. There are currently two sections in the documentation that talk specifically about flexscript which are the FlexSim Coding and Command Reference. The search field does NOT search the command reference. If you want to search that, use the Command Helper from the Help menu (or hover over a command in a script window and hit F1).

The user manual is a set of HTML pages. When you search for something, it works a lot like a search engine. Clicking on a matched link on Google doesn't jump down to a section of the page that has the word you searched for in it. I'm not sure that our search should work differently.

A Kamphaus commented Dec 5, '16

I'm not hearing anything about the index - it would seem like that would give you the most control over what main topics and ideas can be presented to a user...are you doing away with the index?

· 3

Phil BoBo ♦♦ commented · Dec 05, 2016 at 05:11 PM

The index is a list of the pages in the User Manual. It doesn't take into account their contents. It isn't an index of key words; it is an index of page titles.

If you want to search the contents of the manual and not the titles of the pages, use the Search tab.

The field at the top of the Index isn't a search; it is a filter.

If you know the title of the page you are looking for but you don't know where it is categorized in the table of contents, you can use the index to find that page by its title.

If you are searching to find a page based on keyword(s), use the Search tab.

1 ·

A Kamphaus Phil BoBo ♦♦ commented · Dec 06, 2016 at 07:06 PM

Thank you, this explains why I'm getting the results I'm getting.

0 ·

Joerg Vogel commented · Dec 05, 2016 at 05:29 PM

I got a private answer to this topic, too. If you open the Users Manual space you see a list of all Posts. In the second line you find the path to the post or topic. If you open a post which is in the manual branch of your interest you will get the Navigation tree on the right side of the window of your browser. The Navigation tree is the table of contents.

0 ·

Idea

Updates to User Manual Search Capabilities

3 Comments

Write a Comment

Things to know…

Your Opinion Counts

IDEA DETAILS

Related Ideas