I had given suggestion on the documentation part couple of months ago. However, I don't see any reply or changes in the documentation, hence putting it again here:
If you look at any documentation like API gateway, OAuth toolkit you will notice that there are no practical explanations on how this assertion can be used in to achieve it's goal e.g. From API gateway documentation on Authenticate User or Group Assertion , you will notice good theoretical explanation on each property and usage but not explained with any practical example. Below are few my suggestions with respect to documentation part
1. For each type of technology say API gateway, MAG or OTK, categorize the documentation into 3-4 sections, e.g. for API gateway documentation, create 3 categories like API development, Administration and Support activities. Development: developing API, Administration: install, configure, etc. and for Support: how to monitor and troubleshot
2. Explain every assertion with practical examples showing policy manager snapshots, created xml structure, etc. It will be good if you put quick video say for 4-5 mins which explains assertions's usage with practical demo
3. A document section on few best practical demos on showing most of the critical assertions used as per industry standard.
4. A document section on common set of issues faced during development, maintenance and support activities and their solutions with examples
if above items are considered then it would be very useful for every gateway engineer to understand the CA L7 products. Having good documentation will build confidence in developers, management and business owners.
------------------------------
Technology Lead
Infosys Limited
------------------------------