Re: [boost] [Important] Boost moving to Subversion on Tuesday, July 31st

From: Matias Capeletto (matias.capeletto_at_[hidden])
Date: 2007-07-27 15:47:08

On 7/27/07, Rene Rivera <grafikrobot_at_[hidden]> wrote:
> Doug Gregor wrote:
> > On Jul 27, 2007, at 2:43 PM, Rene Rivera wrote:
> > My feeling is that developer-centric documentation should move to the
> > Trac Wiki, where it can be easily modified/updated by all of our
> > developers.
>
> Hm, I don't think editing the new website is any harder to
> modify/update.

IMO editing a wiki page is easier.

> I worked hard to come up with a structure that makes it
> easy.

This is great, and it will be very good for used docs.

> All it takes is the svn access and a text editor. Or if editing
> XHTML directly is dreadful to you, there are many "visual" editors out
> there that will work.

You need a lot of things. Past week I edit the IBD wiki from my
grandmother old computer using just firefox :)

> > It doesn't really need to be on the main web site.
>
> Depends, on what you mean by "developer-centric".

I think it is every thing that a user-only booster will not find
useful. For example, how our svn is organized.

> Sure we have multiple
> audiences but we have to consider that there isn't much difference
> between prospective and existing Boost developers.

If you separate users and developers you can write better and more
direct docs, It is very different how you write when you now a
developer is the target. This is the same reason we separate the
Rationale from the Tutorial in our lib docs.

> And that making an explicit distinction between them is likely detrimental to making
> prospective devs into active devs.

IMHO it will not. And I plan to actively get more boost-users involved
in Boost development.

> But overall I prefer to have docs in the svn/website as it allows for better quality control.

It is a compromise. I think that the developing process will benefit
from the flexibility that a wiki gives you. And I do not agree we can
not developed quality docs in the Trac Wiki.

I think that IBD wiki has a very high quality:
http://svn.boost.org/trac/boost/wiki/ImprovingBoostDocs

And the wiki allows people to easily collaborate making it better,
check the work of IBD proofreaders (thanks Jake and Paul!)
http://tinyurl.com/3234qk

With respect to user docs, I agree that the best place is the website
and the boost release package.

King regards
Matias