Announcing New InterSystems Product Documentation UI (beta)
We have put a new modern and responsive UI design on top of our existing product documentation. It is available in a public beta here: http://docs.intersystems.com/beta/csp/docbook/DocBook.UI.FramePage.cls
Please review the new design and give us your feedback.
Note: the Class Reference UI has not been updated and all product documentation content is the same as what's in production now.
Comments
This looks much better. What about class reference?
Class reference styling will come soon, pending some debate on the usefulness and functionality of the class reference itself.
Please don't remove class reference.
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.
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.
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.
I didn't actually test it on a phone/tablet, just resized browser window. Maybe it's OK on mobile devices.
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=G…
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.
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.
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.
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
Thanks for the feedback. Yes, we will add filtering capabilities to narrow your results.
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.
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.)
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.
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?… 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.
Completely agree, and one of the first shortcomings I noticed. Search bar should ALWAYS be an option an any page, at any time.
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.)
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?
Yes, this is using the same DOCBOOK content. We just put a different UI on top of it.
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.
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?
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.
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?…
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?…
However, that only takes you to the beginning of the page and not to the actual section (in the same page).
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.
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.
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
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.
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.
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
Nice UI, but improve the searches is a very good idea
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…
Once you have done this you will be able to run docbook search from the searchbox in the upper right of your browser.