New post
Article
· Apr 20, 2016 1m read

Feedback on Product Documentation?

#Caché #Ensemble

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

Discussion (15)2
Log in or sign up to continue
Francis Galiegue · Apr 20, 2016

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

2 0
Paul Gomez · Apr 25, 2016

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.

http://docs.intersystems.com/

0 0
Paul Gomez · May 5, 2016

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.

0 0
Mike Dawson · May 6, 2016

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.

1 0
Paul Gomez · May 6, 2016

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.

0 0