Announcing New InterSystems Product Documentation UI (beta)

Evgeny Shvarov · May 11, 2016

This looks much better. What about class reference?

1 0

Paul Gomez · May 11, 2016

Class reference styling will come soon, pending some debate on the usefulness and functionality of the class reference itself.

0 0

Eduard Lebedyuk · May 12, 2016

Please don't remove class reference.

1 0

Paul Gomez · May 12, 2016

We recognize there's a need for a class reference, so don't worry, it's not going away. The question is about functionality and completeness of the current class reference utility so there may be some refactoring in addition to changing the UI skin. There's some internal discussion about how it works and the way the information there is obtained. They'll be more on this in the next few weeks.

0 0

Sergei Shutov · May 11, 2016

Looks nice! A few things to consider:

- On MacOs Safari header text is white on white background

- On small (mobile) screens there is a huge 230px right padding in .book class, page looks much better without it

- On small screens, it's better to hide left menu by default and let user expand it with menu button, like https://material.angularjs.org does. Also it should overlap or shift main text, otherwise both are unreadable.

0 0

Paul Gomez · May 11, 2016

Thanks for the feedback. I didn't see the large right padding on the iPhone or an Android tablet but maybe something changed. We'll check that out and the other comments.

0 0

Sergei Shutov · May 12, 2016

I didn't actually test it on a phone/tablet, just resized browser window. Maybe it's OK on mobile devices.

0 0

Mark Hanson · May 11, 2016

On the initial page displayed if you click on any of the links such as the Improved SQL Processing Performance item it takes you to a link which eventually times out, looks like these are missing the 'beta' as the first part of their url:

http://docs.intersystems.com/csp/docbook/DocBook.UI.FramePage.cls?KEY=GC...

0 0

Paul Gomez · May 11, 2016

Thank you. Last minute decision to deploy to docs.intersystems.com/beta vs. a completely different alias throws off those references which need to be relative to the root. We'll fix this on that landing page.

0 0

Mike Kadow · May 12, 2016

Paul,

First of all, thank you, it seems you have taken on a huge project here, I commend you for it.

Now, two questions,

1) Does it handle multiple searches like Google does. When I separate several words by a comma? And the comma indicating an "And" condition. ie: if I want to search for Cache AND Loops with search "Cache, Loops"

2) When getting search results, would it be possible to put the results in a new Tab in explorer?

Again, thank you.

0 0

John Murray · May 12, 2016

Thanks for posting this. I shall try and remember to use the link routinely for my exploration of the docs, as a way of testing the beta.

0 0

Kevin Furze · May 13, 2016

can you introduce cookies (or something similar) to allow you to totally disregard any results in certain areas.

for instance, I'm a small developer and so I do not use Ensemble, DeepSee, Iknow and so on.

also if you are on window, prehaps you could filter out VMS, Unix etc

narrowing down searches fasst is often the clue to finding what you are really searching for.

perhaps a filter with a series of tickboxes (defaults to everything)

kevin

1 0

Paul Gomez · May 16, 2016

Thanks for the feedback. Yes, we will add filtering capabilities to narrow your results.

0 0

Dmitry Maslennikov · May 13, 2016

Many times I need to get some link from documentation, to show particular part to someone. And some time it is quite difficult to get such link, and the worst place in Class References, where I can't get good link for a particular part of class.

So, what I need is, an active icon with link, which then I can use, and for Class reference too.

As an example github.

3 0

Mike Wragg · May 17, 2016

Great idea. (I find SharePoint frustrating. All I want is a simple link to a folder in a library, but it's really hard to get.)

0 0

Paul Gomez · May 17, 2016

Thanks for the feedback. I'll see if we can do some kind of "copy link" icon at the book/section level to make it easier to reference a particular section of the content.

0 0

Stephen Canzano · May 17, 2016

One aspect that has been lost in the transition is to have the Search Dialog always on the page. If you go to this page as an example http://docs.intersystems.com/beta/csp/docbook/DocBook.UI.FramePage.cls?K... in order to initiate a new search it appears I have to

Select this back button on the top left hand corner
Scroll the left hand side menu, list of books to the very top
Place my cursor in the search field and enter a new search term.

Whereas in the old system I could

Press the [Home] key to be taken to the top
Enter a new search term.

I would vote to make the search box visible at all times.

4 0

Evan Parton · May 17, 2016

Completely agree, and one of the first shortcomings I noticed. Search bar should ALWAYS be an option an any page, at any time.

2 0

Mike Wragg · May 17, 2016

Yep, that's the first thing I noticed as well. I often go from one search to another and do not want to step back to the start each time. Search is probably the most important facility for me. (Thanks to interSystems for opening it up for comment, by the way.)

0 0

Stephen Canzano · May 17, 2016

Just checking as I still see Technical Articles I assume if you add content to DOCBOOK this additional content will still be part of this new UI?

0 0

Paul Gomez · May 17, 2016

Yes, this is using the same DOCBOOK content. We just put a different UI on top of it.

0 0

Evan Parton · May 17, 2016

Browsing (top-level) tree-view of topics is not possible when you've drilled into a section.

Browse in left pane to a book and section to view. Clicking into that section brings you to the doc page, however it also restricts the tree-view in the left pane only to the current book. To further browse all docs, you need to go 'back' (which removes the doc you've been viewing!).

I'd want the possibility to browse in the left pane to a new section without losing my view of the actual page in docs in the right pane. Often it is helpful to keep the view of the actual doc page while browsing to your next (related) topic.

2 0

Paul Gomez · May 17, 2016

Interesting observation, thanks. So if the user is looking at the contents of a book, but in the left pane chooses Back, leave that book content visible until they choose something else?

0 0

Evan Parton · May 17, 2016

Yes, exactly. Thanks.

Preferably there is some smooth way of backtracing these bread crumb trails that are maintained in that left pane. Can the back button smoothly transition back to the higher level tree-view? Essentially as I drill down the high level view of the documentation books, can each section and subsection be displayed while leaving the highest level of books still within browsable view? I don't see why this concept of a 'book' needs to be restrictive against transparently browsing multiple topics among multiple books.

0 0

Fabian Haupt · May 17, 2016

It seems in page anchor links are broken. For example on the CSP Web Gateway Management Page:

http://docs.intersystems.com/beta/csp/docbook/DocBook.UI.FramePage.cls?K...

In the secion "Event Log Level" there is a link to "Event Logging Parameters" (which would go to: http://docs.intersystems.com/beta/csp/docbook/DocBook.UI.FramePage.cls?K...

However, that only takes you to the beginning of the page and not to the actual section (in the same page).

1 0

Evan Parton · May 17, 2016

Regarding the 'Search' functionality:

1) Special symbols such as $ now are searchable (without specifically adding quotes) -- excellent, great improvement!!

2) Searching WITH quotes fails to perform same search:
Due to above, searching both $d and $data (without quotes) works correctly. Now notice the failure of the same search with quotes: "$d" (no $data results at all) and "$data" (appropriate result 17 items down).

3) When the search query contains quotes, the summary at the top of the page fails to decode the special characters ("). For example searching "$data" will display at head of result page:
Matches in text: 1 - 20 of 76 for "$data". (.00029s)

4) Following a link from the Search Results page doesn't allow for respecting the in-page 'Back' button. It's unclear if this is the intended use of 'Back'. By landing on a doc from search, using the 'Back' button does not return the user to the previously used page (the search results), but instead goes to a higher level in tree-view.

2 0

Chad Severtson · May 17, 2016

The version of the documentation should be clearly displayed as there are differences between the respective versions (and not just in appearance).

The ordering of the sidebar is confusing to the point that I find it distracting.

1 0

Kevin Furze · May 17, 2016

I think its absolutely essential to be able to use similar syntax to google etc.

example the use of minusSearchWord or phrase.

it's just become so natural to start excluding words when you see topics within the results that are irrelevent.

so I want to be search for able to

rest -deepsee -csp

1 0

Stephen Canzano · May 17, 2016

Given that you guys have opened the hood, while not specifically a DOCBOOK request, I would like to see https://www.chromium.org/tab-to-search be supported for DOCBBOOK content. As an example I'd like to when using Google Chrome be able to type

docs.intersystems.com [tab] {SearchTerm}

and have the page respond with a list of results based on {SearchTerm}

I understand there may be issues with what version of DOCBOOK to show but it might be useful to just show results from the latest version.

1 0

Bill McCormick · May 18, 2016

Just to clarify for people. We are not working to enhance DOCBOOK searching. You can use Google search today.. right now.. on our current documentation set via the community. This is an attempt to modernize the layout and look of what DOCBOOK presents once you have clicked a search result and displayed what you get.

0 0

Dmitry Maslennikov · May 18, 2016

It's is not good idea, not all time and not everywhere I have an access to google, but I have an access to my installation, and I have to search on my local machine. And such search should be support browser's search engines. And then I could do something like this.

with settings

But Ensemble documentation, should provide their own search engine to install in my browser without any manual operations. As it possible to do with AddSearchProvider

2 0

David Reche · Jun 2, 2016

Nice UI, but improve the searches is a very good idea

0 0

Sascha Kisser · Jun 3, 2016

In browsers Chrome and Vivaldi you can add the new documentation as search engine:

Open settings - search - add new search engine

The URL you need is: http://docs.intersystems.com/beta/csp/docbook/DocBook.UI.SearchPageZen.c...

Once you have done this you will be able to run docbook search from the searchbox in the upper right of your browser.

0 0