Quite some time ago, Dave Abrahams announced that I was the new Boost Documentation Wizard. I said I'd write something on the subject and that is long overdue. Herewith, I describe what I think the DocWiz should do and what is needed from volunteers to make it happen. That is, I'm trying to document the new DocWiz role and solicit your help. Please have a look and comment on what I'm proposing. If you don't like the direction I'm planning, say so. If you think I've missed something, let me know. If you think you can help in some way, please let me know; I can't do the job alone. The DocWiz's purpose is to try to foster better documentation for Boost. Since this is something new at Boost, some measures will be grandfathered* of necessity, while others will likely be retrofitted to existing documentation. Some things will be purely stylistic, but most will be substantive. A significant problem with writing library documentation is that English is often not the library author's primary language.* It is all too common that those who can write C++ fluently cannot write English well. Thus, we need a means to ensure that the library author's ideas are well communicated. Another problem with writing library documentation is knowing what to write. How much detail is sufficient? How many code examples should there be? How much material should be relegated to a reference section and how much should be presented in a tutorial? What is a sufficient rationale for the library? Many of these issues can be addressed by seeking insight from what has been written well already and by seeking advice from those expert on the tasks. From that information we can capture best practices to assist new documentation authors. Still another problem is consistency. As Boost grows, having a reasonably consistent look and feel to our documentation becomes increasingly important. Naming and organizing sections in our documentation must be consistent across libraries to simplify locating desired information in each library. Given the rate at which new libraries are proposed, I cannot do this task alone. I'm the father of eight (yes, 8!) children (so far, at least), I have a full time job, etc. Like everyone else, I'm quite busy. Thus, I need help. I intend to be the manager of a group of folks who can divide the workload to make it manageable. To that end, I propose the following positions to assist in improving the state of Boost documentation: Editors - Folks with demonstrably good English skills who can assist library authors by clarifying and correcting the documentation at various times, as determined by the author, so the meaning is clear. Editors also advice the author on structural changes necessary to conform to Boost guidelines. Editors are not so much concerned with content as with clear communication of what is included. Domain Experts*** - Folks with special skills in writing certain types of documentation such as concepts or tutorials; when a library author is struggling to write a portion of the library's documentation, the author can call upon the appropriate domain expert for assistance. Mentors - Folks with skills and desire to write good documentation who can come alongside a new library author to ghost write, share writing tasks, suggest content, etc. The output from author/mentor collaboration must still be approved by an editor. The workload of an editor will be varied since the number of authors writing documentation varies and based upon their update schedules. The workload of a domain expert should be quite low as folks writing concept descriptions, for example, should not need a domain expert's input often or long. The workload of a mentor likely will be as high as the mentor wishes. Initially, anyone acting as an editor will need to prove his/her skills by relying on trusted editors to proof the results. Once proven, a new editor can act autonomously. The expected result of this group of folks is documentation that is acceptable to Boost. I propose that a library cannot be fully accepted by Boost without the DocWiz's approval. IOW, a library can be conditionally accepted pending documentation approval. (That approval may be given based solely upon the word of a trusted editor; the DocWiz needn't read every document to give approval, but the responsibility does lie with the DocWiz for deficient approved documentation.) Note that the DocWiz is not the final authority on what is acceptable documentation. Users of that documentation are. An author will likely need to update documentation based upon user experience. Such changes should be subject to an editorial review, too, in order to maintain high standards. -------- * That means that existing documentation needn't be changed to conform to new policies, but may be if the author chooses. ** Another problem is that English *is* the library author's primary language. :) *** The name "domain expert" smacks too much of someone who is expert in the domain of the library rather than of a particular aspect of library documentation. Please suggest a better name. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;