On 1/26/17 2:05 AM, Niall Douglas wrote:
I'm gratified that you've taken the task of documentation as an integral part of developing the library. I've been flogging this idea in the boost incubator. I've got a lot to say about this there.
I would more describe it as a cross to carry whilst being whipped on the road to Golgotha. Lucky I'm Catholic. I'm reaching the point where I'd prefer a broken arm to rewriting the damn tutorial yet again, the fact people need stuff spelled out to them in such incremental and precise detail and can't just mentally fill in the very obvious small gaps I find extremely frustrating.
Still, as you would say Robert, that's the price of good documentation.
** warning ** off topic rant you've probably been exposed to before. TL;DR I think you're feelings about writing documentation are widely shared. And I think this is big problem for everyone. It works well for me to write the tutorial while I'm writing the code. I go back and forth between example, reference and code more or less at whim. I think of the tutorial and reference are aspects of the code. The reference is basically a form filling exercise - concepts, types and free functions. The code is types and free functions. When I start coding I don't really plan much - it's sort of free form. I write some code and write an example to be able to compile it. I have to do this because it's header only code. When I think I like it, I add the tutorial narrative and fill out the type/function form. Of course at this point I discover a lot of errors. Often the concepts need to be shuffled around, and this ripples through the code. At this point, it's still a small project so this isn't too painful. I've now convinced myself that this is going to be easy - all I have to do is add a few more examples and make sure they work. Of course this an illusion. Like I'm just going to pull this one loose thread out of my sweater. BUT I do have one thing "done" so I can't throw away my "finished" work and I'm motivated to push on. For this to work one needs to have a painless way to make documentation as one proceeds without having to get sucked into a lot issues like presentation, organization, etc, etc. For me Boost Book has worked for me to isolate me from this "noise". I have great tool for editing boost book with a wysiwyg editor so it's quite painless. It's really part of tool setup. IDE for code, BoostBook/XMLMind for documentation, Git for revision control of both the code and documetation. They are always in sync and I can go back, branch etc. The only really weakspot and source of pain is CMake/b2 which always cause problems. Normally programmers write all the code and then try to document it. This is agonizingly tedious. In practice, the documentation ends up as an after thought is is out of sync with the code - and it shows. Also writing the docs and tutorials always reveals problems in the library design. But now it's so late in the process and the ripple effect is so large, it's just to painful to fix and we just say "good enough". I spent too much time on this already. This probably explains why 99% of "open source" code has not documentation at all. Robert Ramey
Niall