[IBD] Request for Comment, Objectives
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.
On 7/8/07, Matias Capeletto <matias.capeletto@gmail.com> wrote:
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.
To add to Matias' description: Since Matias is attempting to draw non-C++ers into the community through the Boost Docs project, I think that being ostensibly professional, yet fun would do a lot to draw in individuals. This is not unprecedented in the OSS community in the least. Go to the Ubuntu main page for example.. the first thing you see is a diverse group of people who have clearly been blown backwards onto the floor from the level of fun they experienced while using Ubuntu. Ubuntu has had quite a bit of success and attention, so emulating some of what they do could be prudent.
* Achieve an unified look and feel between docs and Boost resources, integrating them as much as possible.
I think that consistency should also be a goal of the documentation (better to make changes now than when Boost has 500 libraries and has turned sentient). Using your Boost.Bimap documentation as an example (which is actually the most remarkable library documentation I've ever seen, so I'm glad that you are heading this initiative), adding a "One Minute Tutorial", "Reference", "Performance", "Compiler", etc. section to all libraries will help people find what they need a lot faster. This is just an idea, though.. I'm not asking all library authors to revisit libraries they wrote 5 years ago and redo the documentation. This could be a productive effort for the documentation community (which I will work with following GSoC). All of the current Boost documentation show their authors' biases towards what useful documentation is: some focus on hand-holding for beginners, others speak more heavily in the language of the C++ standard. Beginners / people who aren't interested in the finer details can just go to the "One Minute Tutorial" section and be on their way, and coders who really like to know what's going on, and know all the options, can go to the reference section
- 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.
Have you considered contacting projects with an existing documentation system (PHP, Python, Ubuntu, etc..) and ask for recommendations/advice?
* 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.
I think you'll get a few more offers for help if you were to make it clear to the outside world that you are looking for help. Getting the documentation effort added to the "Participation" section on the front page could be one way to do this. Jake
Jake Voytko wrote:
To add to Matias' description: Since Matias is attempting to draw non-C++ers into the community through the Boost Docs project, I think that being ostensibly professional, yet fun would do a lot to draw in individuals. This is not unprecedented in the OSS community in the least. Go to the Ubuntu main page for example.. the first thing you see is
a mediocrely designed, ad-laden, image-laden web page with five sentences of information. The documention is several clicks away and looks like an ordinary wiki. I really hope this is not how Boost will look in the future. Regards, m
I did not suggest that we become Ubuntu.. please don't put words in my mouth ;). What we *should* do is take what works from the most successful communities. Go to their front page, and you see people smiling, and you also see the left nav essentially screaming "Develop! Help out!" I don't think it's any mistake that distrowatch.com lists them as the most popular Linux distribution. You're wanted there, and they make that clear on the front page as one of the most noticeable set of icons. If the goal is to have people be involved with the documentation, try to get cues from other projects that have big documentation communities. What did they do to get this way? Jake On 7/8/07, Martin Wille <mw8329@yahoo.com.au> wrote:
Jake Voytko wrote:
To add to Matias' description: Since Matias is attempting to draw non-C++ers into the community through the Boost Docs project, I think that being ostensibly professional, yet fun would do a lot to draw in individuals. This is not unprecedented in the OSS community in the least. Go to the Ubuntu main page for example.. the first thing you see is
a mediocrely designed, ad-laden, image-laden web page with five sentences of information. The documention is several clicks away and looks like an ordinary wiki. I really hope this is not how Boost will look in the future.
Regards, m
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Jake Voytko wrote:
I did not suggest that we become Ubuntu.. please don't put words in my mouth ;). What we *should* do is take what works from the most successful communities. Go to their front page, and you see people smiling, and you also see the left nav essentially screaming "Develop! Help out!" I don't think it's any mistake that distrowatch.com lists them as the most popular Linux distribution. You're wanted there, and they make that clear on the front page as one of the most noticeable set of icons. If the goal is to have people be involved with the documentation, try to get cues from other projects that have big documentation communities. What did they do to get this way?
Whatever they did, it's probably not the quality of the documentation that made them successful (randomly picked example: https://help.ubuntu.com/7.04/keeping-safe/C/users.html found under "Keeping Your Computer Safe" doesn't say a single word about password quality (and there would be many other things to say in the context of user management)). Boost isn't in a popularity contest. I don't see any point in referring to the success of the Ubuntu community as long as their (documentation) results look pretty sad. Regards, m
On 7/8/07, Jake Voytko <jakevoytko@gmail.com> wrote:
On 7/8/07, Matias Capeletto <matias.capeletto@gmail.com> wrote:
* Achieve an unified look and feel between docs and Boost resources, integrating them as much as possible.
I think that consistency should also be a goal of the documentation (better to make changes now than when Boost has 500 libraries and has turned sentient). Using your Boost.Bimap documentation as an example (which is actually the most remarkable library documentation I've ever seen, so I'm glad that you are heading this initiative), adding a "One Minute Tutorial", "Reference", "Performance", "Compiler", etc. section to all libraries will help people find what they need a lot faster.
We have a section for this kind of formal proposals: http://svn.boost.org/trac/boost/wiki/DocumentationBestPractices It is empty at the moment, but we will surely add something about a suggested section layout. There is a precedent in Boost. Look for documentation in this page: http://www.boost.org/more/lib_guide.htm#Guidelines
This is just an idea, though.. I'm not asking all library authors to revisit libraries they wrote 5 years ago and redo the documentation.
It is very important to note that we will not going to impose anything. If we need to standardize something (like the use of docbook for documentation) we will write a formal proposal and present it to the community for review.
This could be a productive effort for the documentation community
We can offer our help to libraries authors.
(which I will work with following GSoC).
We will be waiting for you Jake :)
- 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.
Have you considered contacting projects with an existing documentation system (PHP, Python, Ubuntu, etc..) and ask for recommendations/advice?
IBD is two weeks old. Once we define our objectives we can check others projects. I have take a look at PHP, Python and Ubuntu docs and the content of them is not any better than in Boost docs. The big difference is that they have a consistent structure and style through the complete set of docs. In a short googling (I can not assure this) it seems that PHP and Ubuntu are using Docbook, and Python is using LaTex.
* 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.
I think you'll get a few more offers for help if you were to make it clear to the outside world that you are looking for help. Getting the documentation effort added to the "Participation" section on the front page could be one way to do this.
Maybe in the future. Right now we must clearly define our goals and build a solid base for the project. Best regards Matias PS: How much time to the SoC end Jake? ;)
on Sun Jul 08 2007, "Matias Capeletto" <matias.capeletto-AT-gmail.com> wrote:
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.
I agree that developing a consistent and improved look & feel is important. However it is at _least_ as important to develop skills and best practices that produce good documentation content. That means, among other things: * learning to write precisely, without ambiguity * learning to think about your code as though you don't already understand it * learning to omit needless words * learning to set expectations appropriately. Producing quality documetation typically takes as much -- or more -- time than writing the code that is documented. etc... I don't know who is watching out for these things, but IMO they are essential elements of any effective IBD campaign. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com The Astoria Seminar ==> http://www.astoriaseminar.com
On 7/8/07, David Abrahams <dave@boost-consulting.com> wrote:
on Sun Jul 08 2007, "Matias Capeletto" <matias.capeletto-AT-gmail.com> wrote:
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.
I agree that developing a consistent and improved look & feel is important. However it is at _least_ as important to develop skills and best practices that produce good documentation content.
That means, among other things:
* learning to write precisely, without ambiguity
Ok.
* learning to think about your code as though you don't already understand it
Very difficult one for the author, at least it was in my case. We can help authors because we it is not our code.
* learning to omit needless words
Important one. In my case, I have asked help to others to reread my docs and they have delete a lot of unnecessary words leaving the text more clear and to the point.
* learning to set expectations appropriately. Producing quality documetation typically takes as much -- or more -- time than writing the code that is documented.
Totally agree.
etc...
I don't know who is watching out for these things, but IMO they are essential elements of any effective IBD campaign.
I will add this points to the objectives of IBD under quality documentation, and mention that we will help authors to improve their docs content. Thanks for spotting a clear miss from the objectives. King regards Matias
participants (4)
-
David Abrahams -
Jake Voytko -
Martin Wille -
Matias Capeletto