Feedback on Product Documentation?
We are in the process of putting a new UI on the existing product documentation, including a mobile-optimized view. We also plan on releasing additional "solution based" documentation that is targeted at common usage scenarios or important configuration tasks.
We are interested in your feedback on our current product documentation - what you like and dislike and especially what changes you would expect to see to make it as useful as possible.
Here's a sample screenshot of the new documentation UI:
We have also adopted a new URL for the latest product documentation, which can always be found here:
http://docs.intersystems.com/latest/csp/docbook/DocBook.UI.Page.cls
Comments
Hello!
First things first: /latest/ is a great idea!
Now, on to my personal feedback which is obviously biased: I am primarily a Java developer (with prior experience in C), and am seeking to know ObjectScript better... As such, I find that two things are fundamentally missing:
- as mentioned in one of my other posts, a reference documentation of changes between the different versions of Caché (introduction of new classes; classes deprecated from n to n+1; changes in classes between n and n+1; or even new keywords): Java has @since, C has manpages and CONFORMING TO, which both give great, useful information... But there is no equivalent in COS documentation;
- an official guide for coding guidelines.
All in all, this is rather a feedback on the content rather than the form; not sure whether this is what you expected, but here be dragons :p
It would be great to see this new docs UI in action. Any chance of open beta?
I know most of the Documentation was written years ago, but it would be helpful if there was screen shots on how to do certain things within the Ensemble GUI editors.
Yes /latest/ is great, but the following seems sufficient to get there:
docs.intersystems.com/latest
About |latest| approach for docs. What if a new release will not contain certain doc chapter - how latest url would work?
404?
Good question. I think we're talking about the case where someone bookmarks content in their browser.
Due to the granularity of the documentation, which is currently at the book/section, it's less likely to result in a 404 since individual books don't get removed often, but there could be the case where a section changes or is removed. With the sections, the navigation is done with HTML anchors, which will still bring up the page even if they are invalid. I will talk to the documentation team to see if there are any other issues.
Another thing to note is that within Developer Community, the documentation has been published in smaller section chunks and this content will be kept up to date, so if you're using the community to find documentation it's not going to be stale. We've also done some work to improve the presence of the documentation content in Google searches, which also will help people find current information on the topics they are interested in.
Bookmarks are another may be rare use case but I meant links to the documentation with "latest" segment in URL f.e. in this article. There are a lot of links to documentation there. What will happen with this links if some parts from documentation will be removed in the next version?
I have two comments on the current documentation:
1) It seems that the documentation is aimed at the developer with an average level of knowledge. Which leaves the beginner totally lost.
2) Many times the current documentation makes leaps of logic, and unless you can leap with it, you are out of luck.
Mike, for additional learning content please see the following:
and our new Learning Management System (currently in beta), which features new learning paths for specific topics and themes and also has all of the Global Summit 2016 content.
On the new URL, what happened to the Feature Map and the Master Index? I use the Index all the time. Has it moved or just been dropped?
Feature Map is discontinued. I'll find out about the Master Index.
When I search for something in Ensemble, I got all of the hits in the other areas as well. Would it be possible to restrict the search to the area of the documentation that you are interested in: Cache, Ensemble, etc.
Hi Randy,
This is just the start and we will be adding new filtering capabilities to the online documentation once we release the new UI. Also, we probably haven't done a great job of advertising the fact that the product documentation is in Developer Community and searchable.
- click on search
- in the search box type in a keyword or phrase, let's try "web service" (without quotes)
- you will then see the search results, along with a selection widget labeled "tags". You can open this and add a constraint to the results. In this case you can select "Ensemble", which will include the child tags under it.
- the results will be refined to only include those tagged with "Ensemble" (and it's children)
- you can also use the Categories filter to choose "Product Documentation" to only see the documentation rather than everything on the site.
My two top gripes with the current documentation:-
Searching. The search regularly fails to find pages that I know are there or shows pages that are not relevant to my search. In the days of powerful internet search engines this is really frustrating and disappointing.
Lack of sample code. They say a picture is worth a thousand words, well some sample code works the same way! Come on guys if you have just documented a class with scores of methods and properties give us some sample code showing normal invocation.
Mike - thanks for the comment. The stand-alone documentation is being reworked, first with a new UI and then with a new search engine. In the meantime you have two other options for searching documentation that didn't exist a few months ago, or were not that effective.
1. Use Google - we've cleaned up (most) of the old documentation references and fed Google's crawlers what they need to index the documentation properly. Example: site:docs.intersystems.com ensemble HL7
2. Use Developer Community's search and then select Product Documentation to narrow the results. All of the documentation is indexed here.
As for the code samples inline with the documentation, this is great feedback and something we will put some focus on.