On 5/12/2018 03:20, Robert Ramey wrote:
I'm aware that this suggestion is made in jest. But I think it reflects the view of many authors that documentation is a chore that can separated from the library development and design which can most expediently left for last, delegated to doxygen or just skipped entirely. I think this view totally wrong. It's a sure sign that the one's library is messed up when documenting how to use it and how it works is too difficult to do. If one is crafting the documents and the code together, difficulties in keeping the documentation working can motivate improvements in the design which make things much simpler. We've had boost submissions where the document is a mess - and generally that implies that the code is also.
+1 Authors must write the first version of the docs, because they're the only ones who know the library well enough to do so. They should remain responsible for the "official" docs thereafter, but incorporate constructive feedback from others on review and trying to actually use them. Things are usually less obvious than the author assumes. :) And design and layout of the documentation is just as important (if not more important) than the design of the code itself. No matter how finely-crafted the code is, a library is useless if nobody knows how to actually use it, or their first instinct is to use it "wrong".