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