Hello Boost, The Improving Boost Docs project is starting to have real man power. There are more than twelve developers right now working on different parts of it, and we are actively trying to get more people involved. Since we want to build a long term subcommunity which main purpose is to continuously improve the quality of Boost documentation, we would like that our main directives be aligned with the Boost community as a whole. Anticipating some recurring critics we have seen during the last two weeks we would like to include a little FAQ before discussing our objectives. A) Why do we need IBD? -------------------------------------------------------------------- We believe that documentation is a first class citizen in a project, on par with the code. An incredible library is useless with out good docs. Although Boost has one of the greatest documentation available in Open Source projects, we think that it can be improved. For example, a consistent look and feel through Boost libraries will help users to understand that Boost is not simple a collection of quality pieces, but an amazing always evolving maze that must be seen as whole. IBD main purpose is to be another quality reassurance mechanism, trying that Boost Docs be in the better shape possible for each release. B) IBD is a waste of resources, that will be better expended on new libraries and bug fixes. -------------------------------------------------------------------- This is an interesting critic that has pop up in a few threads. We encourage you to check: http://svn.boost.org/trac/boost/wiki/ImprovingBoostDocs#People IBD is offering a place where people that is not a C++ guru (yet) has the opportunity to collaborate with the Boost community. Working with Boost docs will inevitably make us better C++ programmers, and augment the possibilities to become a Boost author or help with patches. We are not wasting Boost resources, we are getting more hands to make Boost a better place. C) IBD new style and resources have a less sober aspect than other Boost resources, lowering the quality of Boost as a whole. -------------------------------------------------------------------- We like to "enjoy quality". Our idea is that having fun and produce quality products are orthogonal process, and since we will invest a lot of our time at IBD we prefer to enjoy or work. We go one step further with this and think that a happy developer produces better quality products. We think that this discussion is very important for the health of our project. Your feedback will be really appreciated. King regards The IBD crowd --------------------------------------------------------------------------- Here are the project objectives reproduced in the thread to comfortably discuss each of them. IBD objectives http://svn.boost.org/trac/boost/wiki/ImprovingBoostDocs#Objectives * Build up a long term community of people that cares and constantly improve boost documentation and tools. * Achieve an unified look and feel between docs and Boost resources, integrating them as much as possible. * Quality documentation - Provide correct, current and readable documentation for the Boost C++ libraries, tools, environment and organization. - Generate Glue docs that sees boost as one tied entity, providing real-world examples, best practices for common tasks and tutorials about how to combine Boost libraries together to build high-quality C++ applications. - Provide a publicly available, vendor-neutral reference manual for the Standard C++ library, STL concepts, data types and algorithms as part of the Boost library documentation. - Make it easier for users to navigate through the enormous amount of boost documentation. - Use latest version of standards and support old browsers. - Include nice looking logos and diagrams. Although Boost libraries are so great that they do not need any marketting at all, lets face it: people are attracted like flies to catchy names and fancy pictures. * Documentation tools and support - Improve the docs tool chain, simplifying and integrating it lowering the barrier for people willing to help us. - Develop tools to automate common task, and to make life easier to boost authors. Docs writers should concentrate on generating content and not on figthing with tools. - Work to make doc tools boost-agnostic. We believe that they are useful beyond the boost community, and would welcome anyone who wishes to use, extend or support them. * Generate formal documents about C++ documentation best practices. * Offer our help to libraries authors. This include translations, proof-reading, proposing examples and tutorials for their libraries and helping them with the docs tool chain. * Offer a place where not C++ experts can help the Boost community. In general the tasks we do here does not involve template metaprogramming or others complex C++ machinery. Dessigners, artists, teachers, web experts, Python programmers and Boost users are very welcome along our lines. * Write docs, include rationales, use our own tools. If we want to improve boost docs, we should start by showcasing best practices in this project. * Enjoy our work. If we are not having fun while improving boost docs something has gone terribly wrong.