I think, in most cases, the refereces to the "old way" of ACS 3 in the documentation is very confusing. Perhaps those could be combined into a "What is different from OpenACS/ACS 3" doc. That way the main documentation would be clearer.
Already done for the Install and Tutorial (which takes the place of the old Developer's Guide as the first dev thing people see) and planned for the rest.