suitability is a bit of a tricky one to explain as there are a lot of factors that affect it depending on the profile that is being requested. For the driving profiles, the suitability is based on the speed of the road, where the slower the road speed, the lower the suitability. For profiles where speed isn’t as important (i.e. pedestrian) then the suitability is based on a number of properties relating to the way itself. For example, with the pedestrian profiles things that increase suitability include the class of road (small residential street vs a sidewalk on a main road), presence of sidewalks on higher speed roads, and if the way contains things like tunnels.
You are right though, the documentation should be updated to include some more information about what suitability is, so I will pass this along to those in charge of that.