Re: [boost] [Boost-docs] Maintaining boost.org

Subject: Re: [boost] [Boost-docs] Maintaining boost.org
From: Dean Michael Berris (mikhailberis_at_[hidden])
Date: 2010-05-24 22:27:18

On Mon, May 24, 2010 at 10:41 PM, Rene Rivera <grafikrobot_at_[hidden]> wrote:
> On 5/24/2010 12:09 AM, Dean Michael Berris wrote:
>>
>> If you were at the BoostCon 2010 panel session, I suggested that
>> maintaining boost.org can be a less painful process and that I was
>> willing to help out in transitioning the current site from the way it
>> is currently set up to maybe use Wordpress to host the site. There are
>> other options that I would like to explore only after looking at many
>> different tools and the current process of maintaining it.
>
> There are a few things that might be difficult to achieve when implementing
> the website in a CMS.
>

I have thought about some of these, including the per-library
generated documentation and there are a few things which we can do to
make that a little less painful. The amount of things that can be done
better with a CMS include:

  * Posting of news articles and updates to the developer community.
  * Holding discussions on specific topics or specific subjects.
  * Gathering feedback from the community at large of developers and
users about certain things in context (email works for things like
these discussions and only if people invest in learning the netiquette
required to make discussions on mailing lists manageable).
  * Updating content that is already available.

Wiki's work for collaborative editing but ultimately the site should
cater not only for the developers writing the documentation but be
geared more towards those that are reading it.

I have a few more things to say about this and I'll most probably
write them out in another email for more concrete action.

>> I tried sending mail to the Boost-docs list but I haven't gotten any
>> responses yet so I chose to send another email to the developers
>> mailing list.
>
> Hm, I don't an email on the docs list :-\ I'll cross post to the docs list
> just in case it ever show up.
>

Yeah, I tried 3 times and I wasn't able to get any luck getting the
email to go through. I think this is better held on the developer
mailing list anyway to get feedback also from those who want to chime
in. :)

>> There are a couple of questions I would like to ask and
>> would really appreciated getting an answer about:
>>
>> 1. Is there currently a boost.org web team? If so, who are in the team?
>
> Right now it would be Daniel James, Beman Dawes (for the release docs),
> regular library authors, and myself. Although Daniel has essential done all
> of it.. Since there really isn't that much to do. I think he's spent idle
> time rewriting some pf the PHP scripts from the rather nasty code I
> originally wrote ;-)
>

Ah, alright, thanks for the pointers. Now I know who to ask about
migrating the stuff from the current situation to a Wordpress or
<insert CMS that works here>. :)

>> 2. What is the current process of building the boost.org site? What is
>> the toolchain used and how are changes managed?
>
> When I designed it I wanted to use existing "tools" that developers already
> knew how to use. Hence most of the web site is plain HTML. Parts are PHP
> HTML with supporting PHP class code, for example the libraries list and
> online documentation. The feeds, i.e. downloads and news, are Quickbook docs
> that get translated to Docbook and then filtered with a Python script to
> generate static RSS. They are displayed in the site by PHP from reading the
> RSS and doing minor translation to HTML. The big chunk of PHP code deals
> with the documentation. When looking at the documentation pages a PHP script
> looks up pages directly on the Boost release ZIP archive of a given version,
> uncompresses the file, optionally post-processes it into HTML to fit the
> style (mostly just replaces the header&footer), and spits out the docs.
> Hopefully you've already found the web-site dev instructions
> <http://www.boost.org/development/website_updating.html>.
>

Wow. That's quite a toolchain, thanks for explaining it. I really had
no idea how much work was needed to get the website up to the state it
currently is in.

So we still touch raw HTML? That's a little painful. Even the web
designers/developers I know are moving to haml [0] which is a lot
friendlier for people writing code which eventually gets turned into
HTML by some processor. There are also other tools like Jekyll [1] and
Sphinx [2] which deal with Markdown and Restructured Text respectively
to generate nice static web sites.

[0] http://haml-lang.com/
[1] http://github.com/mojombo/jekyll
[2] http://sphinx.pocoo.org/

Thanks for the link too, I haven't seen this yet. I'll give it a whirl
and see how far I can get to making a contribution to low-hanging
fruit.

>>
>> Pending a "full" proposal I would definitely appreciate thoughts about
>> the matter too.
>
> One idea I had, before Boostcon when the whole where should Boost go
> discussion came up, was to move to using something like the Drupal model for
> sub-projects <http://drupal.org/project/Modules>. Particularly how the
> projects each have their own web area. And also how the groups section area
> of Drupal works <http://groups.drupal.org/>.
>
> Note, I'm not suggesting Drupal (even if I do currently use it). Just some
> of the structure they employ for projects since it does mirror the
> conglomerate project structure Boost has.
>

I agree, and it would be nice if we would use something like Wordpress
MU so that we can have library maintainers manage their own sub-sites.
I can totally imagine something like a mpl.boost.org
blog/documentation site where the users can post comments on articles
and what's going on with the library, and potentially download
prepackaged distributable releases of the library (containing all
other dependencies it may have). I'm still toying around with whether
a web-based forum ala StackOverflow would work on a per-library basis
as well, which can be a totally independent feature should library
maintainers want them for their own sites or not.

Without going into the "let's decouple the boost libraries" discussion
(which should be interesting in itself) it would be good for Boost
libraries to have a place in the web where users can get immediate
support for frequently asked questions, be able to file bugs "easily",
and then be able to engage the communities that follow each boost
library to thrive. The maintainers can then write out rationales,
examples, and other things on the web that they (and users) can point
to for a "canonical" answer that usually gets lost in the mailing list
archives and is buried in sometimes unmanageable contextual
information.

Another thing that would be nice to have would be having mailing lists
for each Boost-accepted library. This allows the Boost developer
mailing list to be a general discussion area about Boost as a whole
and the development process and questions about cross-library
interactions. Much like how Spirit has its own mailing list and active
user/developer community around it -- which I think should be the
model for all the other Boost libraries that are actively being used
and maintained.

I'm sure there's going to be another discussion about subversion and
git, whether to release individual libraries or a monolithic
distribution, etc. but I'd like to start with the website to make it
more inviting to the community to use and interact through it.

Thanks again and I'll write up that concrete proposal soon enough. :)

-- 
Dean Michael Berris
deanberris.com