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

From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2007-07-27 16:13:22

Trying to send this to the docs list again...

Matias Capeletto wrote:
> 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.

Yea, probably :-)

>>> 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.

There have been many instances, over the years, of users asking how CVS 
is structured, where to get stuff from CVS, etc. And recently the same 
for SVN and the sandbox. So I disagree on this one. Perhaps I have a 
more expansive on who users are. I expect them to cover the full range 
of experience.

>> 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.

Perhaps people are just not aware of the currently designed separation 
in the beta website... 
<http://beta.boost.org/development/website_updating.html>. So I'm not 
disagreeing on separation. Just that putting of in "another" web site 
would put some information too far away from interested people. Which 
would result in more questions on the list and possibly turning away 
some people.

>> 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.

Of course it's possible to develop quality docs in just about anything 
;-) But I was referring to a different kind of quality. In particular of 
the documentation being cohesive and well organized with respect to all 
the other docs. Why would I place so much importance on this? Well, 
because a good portion of the questions on IRC and the users list are 
essentially an inability to find the docs on our current web site.

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

Ah, another aspect I've disagreed with in the past ;-) Not the user docs 
in the web site, but what kind of docs to put in the release package. 
One of the goals of the new web site is to reduce the amount of docs in 
the release package, to reduce maintenance. So we have to be careful 
what we include in the releases.

-- 
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo