Re: [boost] Copy editing documentation - SOC project

From: Paul A Bristow (pbristow_at_[hidden])
Date: 2007-03-12 10:44:31

>-----Original Message-----
>From: boost-bounces_at_[hidden] 
>[mailto:boost-bounces_at_[hidden]] On Behalf Of Nava Whiteford
>Sent: 12 March 2007 13:22
>To: boost_at_[hidden]
>Subject: [boost] Copy editing documentation - SOC project
>
>
>Matthias Schabel <boost_at_[hidden]> wrote:
>
>> > FYI, QuickBook already has the reverse-lit feature. It lets you
>> > "import" code snippets from actual code. Rene and I are using it
>> > right now to great effect.
>> 
>> I have to say, as a non-CS person, I'm finding it hard to even keep
>> track of the differences between DocBook, BoostBook, and QuickBook,
>> much less figure out how to accomplish anything with them... Just as
>> a side note, given that documentation is already generally 
>regarded as
>> one of the most painful parts of library development, I think it  
>> would be
>> a good idea for Boost to standardize on one system or another and
>> then provide a good tutorial on how to use it... For example, after
>> browsing all the QuickBook documentation I could find, I still have
>> no idea how to implement the code snippet import feature you
>> described; 
>
>After working with Gennadiy to copy edit some documentation 
>I'd have to 
>agree. Everyone has there own preference, Word, Docbook, Latex 
>etc. but 
>you need some common standard if your going to working 
>collaboratively on 
>documentation, ideally it should be a format the preserves 
>markup in some 
>explicit way.
>
>I know it might be an unpopular suggestion, but have you 
>thought of moving 
>the Boost documentation to a wiki based system?

Quickbook is very close the Wikipedia markup language, so it can be used as easily.

CVS already allows control over who can edit it - avoiding the spamming that would certainly be a problem judging by Boosts current
wikis.

I would suggest that we put draft documents up on CVS (SVN later?) for general editing, and permit the original author to reject
edits before posting his preferred version for each formal release.  I suspect people will just add their extra bits and correct the
typos and it will work smoothly - few things are really contentious - unlike some Wikipedia subject areas.

The problem is to get existing documents like Boost.Test into Quickbook.  A re-write would be a good time to do this - otherwise it
is a major task.

Paul

---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
[phone] & SMS, Mobile [phone] & SMS
pbristow_at_[hidden]