If I weren't (mostly) such a huge fan of Wolfram Mathematica I wouldn't bother to complain (and "in public") about its short-comings, and the documentation system is one of them, at least for the complex projects I apply Mathematica to.This just does not make the grade:
f::usage = "f[arg1,arg2] This function has arguments arg1 and arg2, which are not individually documented, unless I use a tedious newlines and make something up."
Every major programming language has a decent structured way to document functions arguments right in or near the code, but the Wolfram Language does not, and it's a major shortcoming.
The Wolfram Workbench offers some modest documentation support, but it's not well enough coupled to the code, i.e. it requires editing documentation separately from coding, so they can get out of sync easily. It's dangerously WET not DRY.
For any code-oriented developer who is used to documenting functions and their arguments coherently, easily, right there where the code is (and used to staying in their "coding zone"), the current Mathematica ::usage and Documentation Tools are approaches inadequate.
The quality of the documentation itself in the main Documentation Center for the Wolfram Language and Mathematica is mostly excellent.
The Documentation Tools approach (which stores documentation in separate "parallel" folders within a Paclet) may be fine for smaller projects with only a handful of packages with not too many functions.
Webel IT Australia has its own code-oriented help system!
Note that Dr Darren of Webel IT Australia does not just whinge; he solves things. Welcome to the Webel Doc` (structured ::usage generation package) and the HelpF` (for functions) and HelpO` (for "methods") help registry packages:
Which are supported by: