Quality of Documentation

[yogesh]

This is just a general feedback on the quality of documentation.

The documentation is poor and has lots of ambiguities and missing information. The documentation should provide complete information concisely.

For example the docs on the below link regarding uploading of roles states:
https://docs.saviyntcloud.com/bundle/EIC-Admin-v2020x/page/Content/Chapter02-Identity-Repository/Upl...

"ROLE OWNER: Specify the name of the owner for the role."

What do you mean by 'name'?
firstname? lastname? fullname? username? systemusername?
It should explicitly state that it should be username. There's no field called name in Saviynt. This is a technical document, why the use of vague ambiguous terms?

How to form the csv if multiple owners are there? Add them on same line with a comma or do we add new line for each owner? This is not stated.

Again for "Role Type" it says:
"Specify the type of role being created. For example, Enterprise."
Why are you giving an example here, you should provide all the allowed values for the role type. If there are 5 types of roles allowed in the csv update then state all those five types, make the documentation complete. Do you want the developers/users to do hit and trials if they want to upload other types of roles?

Same issue with rest of the fields, SOX CRITICAL/RISK, list down all the allowed values in the correct case that can be put in the csv.

This is not something specific to the above page only, but is a common issue I have felt with the entire docs. Some times it feels like the person writing the docs has just opened the UI and is describing whatever is visible adding no useful information.

Another example regarding enterprise role request query : 
https://docs.saviyntcloud.com/bundle/KBAs/page/Content/Use-case-of-Request-Roles-Query.htm

On this page only one example is given, when instead the documentation should first list down all the exposed variables/tables that can be used in these queries. And details about those variables and then should jump into examples. There is no page which has this information.
It mentions {currentUser} but doesn't tell what this exposes, yes from the query you can tell it exposes logged in user's id, or maybe the person you're requesting for? what properties does this object have? Guess what, you'll have to do hit and trial.

I know the 'complete' list of such variables/objects can be huge but it's like you're not even trying.

[Dave]

Hello @yogesh - Thank you for your feedback! We are always looking for ways that we can improve and exceed our customers expectations. I have alerted the Documentation team about your post.

As we are getting into the weekend, I would expect a reply and follow-up by next Monday. Thank you for letting us know your thoughts concerning the documentation. 

Dave

[uthra_rahul]

Hello @yogesh 

Thank you for sharing your feedback on the forum and via the Documentation Portal.

We are currently revising our documentation and publishing incremental updates on the new Documentation Portal.

We will update these topics based on your feedback and notify you as soon as the revised copy is available.

Regards,

Uthra

[stevemcg9899]

@yogesh - have you seen any marked improvements to the documentation since your comment?

FWIW I completely agree with your statement 👍

[yogesh2]

Unfortunately no, documentation is still not even close where I would like it to be.

I honestly think the quality of Saviynt documentation undermines Saviynt as a product.

So many times I have came across stuff that is only mentioned on forums either by a user/saviynt employee but there's no mention of that information in the documentation.

Even implementing standard use-cases is a pain if you're just following the docs. 

For example recently I was trying to import lastlogondate from Azure to Saviynt in account's lastlogondate field (using REST connector as AzureAD connector doesnt support reading this attribute). Saviynt was not being cooperative and throwing errors like out of bound and format errors. I know what the problem is, date is not in correct format, but how to I get to the correct format? This is not mentioned in the REST Developer's handbook page. (It's more of some scribbled pages and should not be called a handbook lol).

It took me several hours of hit and trial what should have been a no-brainer if docs had the correct information.

I gave below feedback on the documentation page and let's see what happens:

Instead of providing examples willy nilly why can't you write proper documentation?

For example there is no mention on this page that "ImportAccountEntJSON" supports specification of "dateFormat" under "globalSettings" like so:

"globalSettings": {

        "dateFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"

    },

I had to rummage through forums to find this information. Why? because I wanted to import a date into the account's lastlogondate field.

lastlogondate is such a standard thing yet there's no mention on this page how to feed it in the proper format.

Instead of providing so many random examples why can't you just write a systematic document which outlines all the configs that are available to a developer. Like "globalSettings" what configurations it supports? Give bullet points:

1. userSourceList

2. dateFormat

3. ...

Then provide details about what these things do and what puropose they serve.

like so:

dateformat: "<string>" // used to specify the format in which Saviynt expects the dates from the target REST application, so they can be fed to date type fields in Saviynt like creationdate, updatedate, lastlogondate etc. using the "~#~date" notation in "colsToPropsMap" config

Details:

"yyyy" represents the year with four digits.

"MM" represents the month with two digits (01 for January, 02 for February, etc.).

"dd" represents the day of the month with two digits.

"HH" represents the hour of the day in 24-hour format (00 through 23).

"mm" represents the minute with two digits.

"ss" represents the second with two digits.

... so on

(Just take a look how w3schools provides similar info:

https://www.w3schools.com/sql/func_mysql_date_format.asp)

Lastly examples: for Graph API date format will be like below:

"dateFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"

[rushikeshvartak]

Documentation which needs high improvement 

• Database schema - Tables / columns / size mapping 
• Email templates and variable exposed.
• REST connector Examples with different pagination.
• unsupported features 

[uthra_rahul]

@stevemcg9899 Hello! For feedback submitted via the doc portal, we notify the reporter once the issue is addressed and the revised doc is published on the portal. In addition, we are also revamping topics based on ongoing customer feedback.

Are you looking for any specific information?

Regards,

Uthra