From my limited experience here, I would start by saying that you should assume that the Designer will not be 100% correct. It often flags things which are actually syntactically correct and will run fine. Designer really lacks purpose for items, but shines with rules and being able to keep track of it all. At the least you should use designer for rule syntax checks, at the most you could use it to manage your sitemap too. Much more and I don’t know that it has much purpose. Certainly not for me.
Have a read here for some similar points you raise.
I would also add that if you find errors/inconsistencies in the documents then you should create a pull request for the doc on github and submit your changes. I wrote the initial items document for OH2, based on the OH1 docs, and experience I had from my own systems. You are more than welcome to add/edit this if you feel that it might need more clarification in any particular areas. I have been meaning to clear up some of the information around icons as I see a number of posts about this still appearing here…
I absolutely agree that there is still work to be done on the documents to make them clearer. With your/our/everyones input on ways to fix them then it’ll get done.