On 08/12/2014 1:57 PM, Robert Ramey wrote:
Michael Levine wrote
The second -- and from my personal experience, the more difficult -- is the lack of a consistently-written and sufficiently descriptive explanation of the 'what, where, why, and how' of the library: What does the library do? Where should I use it? Where should I not use it? Why (explain the overall design -- why is the library structure like X)? How do I use it?
indeed. This is a key part of the documentation. It's also one of the more difficult to make general statements about. For this reason, although I've tried to make recommendations about this aspect, I'm not making a big deal about this. I've been focusing on the reference part of the documentation because it's an easier sell. Once we can sell this, the rest will be easier. Basically my suggestion would be:
a) intro - purpose of the library with motivating examples. b) more examples and advice on library usage c) rationale - why things were done the way they were and not some other way d) reference e) acknowledgements.
But as I said - this is not (yet) part of the current crusade.
I suppose that the question of priority depends on one's viewpoint. Nevertheless, I completely agree with you that the reference section should be the primary focus at this point. As I'm writing this, a thought came to mind and I'll just throw it out there: the library index (at the documentation page - www.boost.org/doc/libs/1_56_0) has a short one-liner about the library. I wonder if it might be possible to expand this brief summary - even just a bit - to provide a bit more information, about the main use case. This doesn't even need to be done by the library author; just someone knowledgeable about the library. I would volunteer in a flash, but I am absolutely clueless with neither knowledge or experience.
I completely understand the extreme difficulty involved in trying to enforce a specific style and format of the documentation on the library authors.
I've been trying to make my case in regards to content and it's organization. I've consciously tried to avoid specifying style, format, tools etc. We have excellent examples of documentation made with the simplest of tools - see iterators - and very hard to use documentation made with the latest/great tools - see boost units. www.blincubator.com explicitly makes the case in documentation requirements and format, tools, etc is discussed in a totally different section - simple tools.
Your incubator site is a phenomenal idea and the information/directions that you have included there are both extremely clear and sensible. Kudos.
It has already been suggested -- whether one agrees with it or not -- that not all libraries can even fit into the same structure due to the paradigm mismatch. Perhaps this suggests that an approach to documentation standardization should take this into account -- in terms of care of not over-specifying the requirements.
I've taken great pains to address this - see above.
There are quite a few dissenting opinions in this thread's history as to whether the same paradigms necessarily apply to Hana. You have made your point clearly on the matter, but there have been quite a few dissenting opinions, as well. I have my opinions on this discussion, as well, but it's a little off-topic from the rest of this particular message. Perhaps I'll address that in a separate response, if time permits.
From my own perspective, the documentation I've read which has followed this general approach has been much easier for me to follow.
Hallelujah!!!
I intended my previous message as an expression of support of your efforts, from the perspective of a beginner/novice user. Sometimes, it's hard to see that viewpoint with the level of expertise that the vast majority of library developers have.
On the topic of Concepts--
<snip>
It seems that "concepts lite" is shaping up to be the next episode in an on going ten year saga. For me it makes no difference. If it ever makes it and people want to use it - fine. I even provide a table for translating boost concept classes into concepts lite code. But this is not really relevant to my argument.
That was very helpful and enlightening.
Basically the whole concepts discussion/development has been blown way out of proportion:
I couldn't agree more.
Just to make myself clear - the path to better library code is for library authors to specify and verify concepts - and we already have all we need to do that. If the committee want's to spend more time on this - fine - but it won't make any difference unless library writers change their habits.
Is there that much disagreement -- at least within the Boost community -- on this point ? I know that Niall expressed his viewpoint that compiler support is essential before developers should embrace Concepts. I'm not completely sure that I understand his rationale on the matter, and your own arguments have long ago convinced me. Niall: Forgive me if I am misconstruing your previous comments on the matter. I understood your point to be that without compiler support (in the form of Concepts Lite, for now), there are too many limitations with a Library-based system to pursue using it in code. There was also some points regarding whether type restrictions should cause soft errors - being usable for SFINAE and specialization - and/or hard errors. IMHO, this is a moot point: clearly there are use cases for each, and a requirement for Boost.Concept (or its successor - what I've referred to above as Boost.TypeRequirements). Ultimately, in my own extremely limited understanding, it seems that the general issue here can be summarized to some extent that there are a wide range of expectations for a Concepts system. I believe that you have been advocating what I'd characterize as the most fundamental set of requirements. There is a lot more functionality and benefits that a fully-complete Concepts system can offer. I can only surmise that there is a general reluctance to adopt a system that people feel doesn't achieve all of the aims that they expect from it, coupled with a concern for needing to revise code once language /compiler support evolves. I'd really like to hear comments from everyone on this, and would invite everyone -- especially people who disagree with Robert -- to share your thoughts on this: - Is my conjecture correct? Or do those of you who object to Robert's position have other reasons? - Is there anything -- short of full language support -- that you require in order to embrace template parameter Type Requirements? - What are the show-stoppers in Boost.Concept that have led you to reject its use.
I've been following this thread for a while, and thought I'd offer my own thoughts on the matter.
Happy to hear from you - I can always use another opportunity to flog my case.
Robert Ramey
Unfortunately, your preaching to the choir in my case. But I do find your response to provide deeper insight into the points that you have already written on the bl incubator site. Best regards- Michael Levine