Hello, I've copied the guidelines onto the wiki now, you can see them at: https://svn.boost.org/trac/boost/wiki/Guidelines/ Any comments? I've changed the beta site to redirect to them. I haven't linked to them from the front page of the wiki as they aren't 'official' yet. I'll be moving more pages over soon-ish. Any ideas about how the wiki should be structured? Daniel
Daniel James wrote:
Hello,
I've copied the guidelines onto the wiki now, you can see them at:
https://svn.boost.org/trac/boost/wiki/Guidelines/
Any comments?
It's a little unclear whether this kind of stuff should be in the wiki or the regular website. I find the website hard to update and often hard to navigate. So I like the wiki. But then, I'm a tiny bit concerned that given the ease of editing the wiki, it might tend to expand "all over the place". It's the classic tension between a dynamic system driven by independent agents all improving a system simultaneously vs. a tightly controlled effort to make the definitive "perfect" system. Thinking about about, I think the former is a better model as I believe it will better model boost itself in the future. So you might want to expand your horizons a little to consider how the wiki might include a lot more of the information which is currently on the web site. Robert Ramey
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Robert Ramey Sent: Sunday, February 14, 2010 5:54 PM To: boost@lists.boost.org Subject: Re: [boost] Guidelines on wiki
Daniel James wrote:
Hello,
I've copied the guidelines onto the wiki now, you can see them at:
https://svn.boost.org/trac/boost/wiki/Guidelines/
Any comments?
It's a little unclear whether this kind of stuff should be in the wiki or the regular website. I find the website hard to update and often hard to navigate. So I like the wiki. But then, I'm a tiny bit concerned that given the ease of editing the wiki, it might tend to expand "all over the place". It's the classic tension between a dynamic system driven by independent agents all improving a system simultaneously vs. a tightly controlled effort to make the definitive "perfect" system.
Thinking about about, I think the former is a better model as I believe it will better model boost itself in the future. So you might want to expand your horizons a little to consider how the wiki might include a lot more of the information which is currently on the web site.
Agree that the wiki looks the best way forward. Editing is *much* easier - by anyone - but also vulnerable to instability and hacking? Can we copy a snapshot of the wiki to the (definitely read-only) Boost site with every release? I'm also concerned at the difficulty of finding the answers to questions. (The lists are proof that we haven't cracked this - some of the same queries come up again and again). I've not found Google's indexing to work too well with my questions (often when I know that the answer is there somewhere). Searching the wiki pages is faster and often more effective (because you've narrowed the searchable stuff - assuming you have the right 'page'). Paul --- Paul A. Bristow Prizet Farmhouse Kendal, UK LA8 8AB +44 1539 561830, mobile +44 7714330204 pbristow@hetp.u-net.com
Sorry about the very slow reply.
Robert Ramey:
It's a little unclear whether this kind of stuff should be in the wiki or the regular website. I find the website hard to update and often hard to navigate. So I like the wiki. But then, I'm a tiny bit concerned that given the ease of editing the wiki, it might tend to expand "all over the place".
Hopefully people with subversion access will be disciplined. But I think you're right, it should be someone's responsibility to oversee the wiki and keep things ordered. I think this page demonstrates that: https://svn.boost.org/trac/boost/wiki/Guidelines/MaintenanceGuidelines
Thinking about about, I think the former is a better model as I believe it will better model boost itself in the future. So you might want to expand your horizons a little to consider how the wiki might include a lot more of the information which is currently on the web site.
Yes, I plan to move more content there.
Paul A. Bristow:
Editing is *much* easier - by anyone - but also vulnerable to instability and hacking?
Hopefully not, since it's password protected.
Can we copy a snapshot of the wiki to the (definitely read-only) Boost site with every release?
My original plan was to just use the wiki, but I think you might right. By using snapshots, viewing the page will be faster and it'll allow people to freely edit the wiki pages. The workflow would be something like: edit the page, ask on the list for a review, if accepted the website manager imports the snapshot. Sounds okay?
I've not found Google's indexing to work too well with my questions (often when I know that the answer is there somewhere).
Searching the wiki pages is faster and often more effective (because you've narrowed the searchable stuff - assuming you have the right 'page').
If all the pages are under the same subdirectory we can limit the search e.g. http://www.google.com/search?q=site%3Awww.boost.org/development+integral Daniel
----- Original Message ----- From: "Daniel James" <dnljms@gmail.com> To: <boost@lists.boost.org> Sent: Thursday, March 25, 2010 9:25 PM Subject: Re: [boost] Guidelines on wiki
Sorry about the very slow reply.
Robert Ramey:
It's a little unclear whether this kind of stuff should be in the wiki or the regular website. I find the website hard to update and often hard to navigate. So I like the wiki. But then, I'm a tiny bit concerned that given the ease of editing the wiki, it might tend to expand "all over the place".
Hopefully people with subversion access will be disciplined. But I think you're right, it should be someone's responsibility to oversee the wiki and keep things ordered. I think this page demonstrates that:
https://svn.boost.org/trac/boost/wiki/Guidelines/MaintenanceGuidelines
Thinking about about, I think the former is a better model as I believe it will better model boost itself in the future. So you might want to expand your horizons a little to consider how the wiki might include a lot more of the information which is currently on the web site.
Yes, I plan to move more content there.
Paul A. Bristow:
Editing is *much* easier - by anyone - but also vulnerable to instability and hacking?
Hopefully not, since it's password protected.
Can we copy a snapshot of the wiki to the (definitely read-only) Boost site with every release?
My original plan was to just use the wiki, but I think you might right. By using snapshots, viewing the page will be faster and it'll allow people to freely edit the wiki pages. The workflow would be something like: edit the page, ask on the list for a review, if accepted the website manager imports the snapshot. Sounds okay?
Yes, IMO this merits to be experimented.
I've not found Google's indexing to work too well with my questions (often when I know that the answer is there somewhere).
Searching the wiki pages is faster and often more effective (because you've narrowed the searchable stuff - assuming you have the right 'page').
If all the pages are under the same subdirectory we can limit the search e.g.
http://www.google.com/search?q=site%3Awww.boost.org/development+integral
Great. This is what we need. I have tried with http://www.google.com/search?q=site%3Awww.boost.org/BOOST_STATIC_CONSTANT and this give no result. What is wrong? Vicente
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Daniel James Sent: Thursday, March 25, 2010 8:25 PM To: boost@lists.boost.org Subject: Re: [boost] Guidelines on wiki
Hopefully people with subversion access will be disciplined. But I think you're right, it should be someone's responsibility to oversee the wiki and keep things ordered. I think this page demonstrates that:
https://svn.boost.org/trac/boost/wiki/Guidelines/MaintenanceGuidelines
It that a compliment or not ;-) (I'm sure it can still be improved!)
Can we copy a snapshot of the wiki to the (definitely read-only) Boost site with every release?
My original plan was to just use the wiki, but I think you might right. By using snapshots, viewing the page will be faster and it'll >allow people to freely edit the wiki pages. The workflow would be something like: edit the page, ask on the list for a review, if >accepted the website manager imports the snapshot. Sounds okay?
Yes - though I'm not sure if we need formal reviews - just asking on boost-docs list if anyone is unhappy might do as well. And if only we could get the releases more often, we can just snapshot "where the docs are now" - in the knowledge that complaints will be dealt with 'next time?. Paul --- Paul A. Bristow Prizet Farmhouse Kendal, UK LA8 8AB +44 1539 561830, mobile +44 7714330204 pbristow@hetp.u-net.com
On 26 March 2010 12:33, Paul A. Bristow <pbristow@hetp.u-net.com> wrote:
Daniel:
Hopefully people with subversion access will be disciplined. But I think you're right, it should be someone's responsibility to oversee the wiki and keep things ordered. I think this page demonstrates that:
https://svn.boost.org/trac/boost/wiki/Guidelines/MaintenanceGuidelines
It that a compliment or not ;-)
(I'm sure it can still be improved!)
I wasn't commenting on any of the content, but the page is a bit of a mish-mash, it needs a coherent focus. The 'user guidelines' are probably out of place, since users aren't involved in maintenance. I also don't understand why there are 'developer guidelines' and 'booster guidelines' (what's the difference?). In the contents, 'Managing Warnings from Compilers' looks like a small subsection, but is actually half the document. It should probably be moved into a 'how to deal with warnings' article (not under guidelines), with a shorter, more general guideline on this page that would link to the article.
Can we copy a snapshot of the wiki to the (definitely read-only) Boost site with every release?
My original plan was to just use the wiki, but I think you might right. By using snapshots, viewing the page will be faster and it'll allow people to freely edit the wiki pages. The workflow would be something like: edit the page, ask on the list for a review, if accepted the website manager imports the snapshot. Sounds okay?
Yes - though I'm not sure if we need formal reviews - just asking on boost-docs list if anyone is unhappy might do as well.
Not a formal review, more along the lines of a patch review. The post would usually be to the development list, especially for anything which effects 'policy'. For other pages other lists might be appropriate. Certain pages might have a clear owner (such as some of the existing articles) and should be mostly left alone. But I don't like the idea of taking a complete snapshot at some arbitrary point. Maybe if we find that the wiki is moving to fast for whoever manages the site to keep up. But I think we should only do this for a limited number of pages, and that they should be fairly static. Daniel
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Daniel James Sent: Friday, March 26, 2010 1:18 PM To: boost@lists.boost.org Subject: Re: [boost] Guidelines on wiki
On 26 March 2010 12:33, Paul A. Bristow <pbristow@hetp.u-net.com> wrote:
Daniel:
Hopefully people with subversion access will be disciplined. But I think you're right, it should be someone's responsibility to oversee the wiki and keep things ordered. I think this page demonstrates that:
https://svn.boost.org/trac/boost/wiki/Guidelines/MaintenanceGuidelines
It that a compliment or not ;-)
(I'm sure it can still be improved!)
I wasn't commenting on any of the content, but the page is a bit of a mish-mash, it needs a coherent focus. The 'user guidelines' are probably out of place, since users aren't involved in maintenance. I also don't understand why there are 'developer guidelines' and 'booster guidelines' (what's the difference?).
In the contents, 'Managing Warnings from Compilers' looks like a small subsection, but is actually half the document. It should probably be moved into a 'how to deal with warnings' article (not under guidelines), with a shorter, more general guideline on this page that would link to the article.
Agreed - It has just 'growded like Topsy': it needs an editor, guided by feedback, to keep it in some short of shape. (But that should not stop others making changes - still a wiki). Most people are polite enough to say "I've amplified/changed/deleted the section on ... - is this OK"?
Can we copy a snapshot of the wiki to the (definitely read-only) Boost site with every release?
But I don't like the idea of taking a complete snapshot at some arbitrary point. Maybe if we find that the wiki is moving to fast for whoever manages the site to keep up. But I think we should only do this for a limited number of pages, and that they should be fairly static.
I was assuming that they *are* mostly static - so a pretty-much arbitrary snapshot should be OK. Paul --- Paul A. Bristow Prizet Farmhouse Kendal, UK LA8 8AB +44 1539 561830, mobile +44 7714330204 pbristow@hetp.u-net.com
----- Original Message ----- From: "Paul A. Bristow" <pbristow@hetp.u-net.com> To: <boost@lists.boost.org> Sent: Friday, March 26, 2010 5:03 PM Subject: Re: [boost] Guidelines on wiki
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Daniel James Sent: Friday, March 26, 2010 1:18 PM To: boost@lists.boost.org Subject: Re: [boost] Guidelines on wiki
On 26 March 2010 12:33, Paul A. Bristow <pbristow@hetp.u-net.com> wrote:
Daniel:
Hopefully people with subversion access will be disciplined. But I think you're right, it should be someone's responsibility to oversee the wiki and keep things ordered. I think this page demonstrates that:
https://svn.boost.org/trac/boost/wiki/Guidelines/MaintenanceGuidelines
It that a compliment or not ;-)
(I'm sure it can still be improved!)
I wasn't commenting on any of the content, but the page is a bit of a mish-mash, it needs a coherent focus. The 'user guidelines' are probably out of place, since users aren't involved in maintenance.
You are right. These guidelines concerns more how the user can avoid breaking his code when boost evolves, and what s/he can do to improve regression tests.
I
also don't understand why there are 'developer guidelines' and 'booster guidelines' (what's the difference?).
Please, note that these guidelines have not been reviewed. I used the word 'developer' for authors or maintainers. The 'boosters' intendeed any member of the Boost community that can check that the released code follows the maintenance guidelines.
In the contents, 'Managing Warnings from Compilers' looks like a small subsection, but is actually half the document. It should probably be moved into a 'how to deal with warnings' article (not under guidelines), with a shorter, more general guideline on this page that would link to the article.
Agreed - It has just 'growded like Topsy':
it needs an editor, guided by feedback, to keep it in some short of shape.
(But that should not stop others making changes - still a wiki).
Most people are polite enough to say "I've amplified/changed/deleted the section on ... - is this OK"?
Paul, would you like to take care of separating the Managing Warnings from Compilers section? Best, Vicente
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of vicente.botet Sent: Sunday, March 28, 2010 7:57 PM To: boost@lists.boost.org Subject: Re: [boost] Guidelines on wiki
----- Original Message ----- From: "Paul A. Bristow" <pbristow@hetp.u-net.com> To: <boost@lists.boost.org> Sent: Friday, March 26, 2010 5:03 PM Subject: Re: [boost] Guidelines on wiki
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Daniel James Sent: Friday, March 26, 2010 1:18 PM To: boost@lists.boost.org Subject: Re: [boost] Guidelines on wiki
On 26 March 2010 12:33, Paul A. Bristow <pbristow@hetp.u-net.com> wrote:
Daniel:
Hopefully people with subversion access will be disciplined. But I think you're right, it should be someone's responsibility to oversee the wiki and keep things ordered. I think this page demonstrates that:
https://svn.boost.org/trac/boost/wiki/Guidelines/MaintenanceGuidelines
It that a compliment or not ;-)
(I'm sure it can still be improved!)
I wasn't commenting on any of the content, but the page is a bit of a mish-mash, it needs a coherent focus. The 'user guidelines' are probably out of place, since users aren't involved in maintenance.
You are right. These guidelines concerns more how the user can avoid breaking his code when boost evolves, and what s/he can do to improve regression tests.
I
also don't understand why there are 'developer guidelines' and 'booster guidelines' (what's the difference?).
Please, note that these guidelines have not been reviewed. I used the word 'developer' for authors or maintainers. The 'boosters' intendeed any member of the Boost community
that can check that
the released code follows the maintenance guidelines.
In the contents, 'Managing Warnings from Compilers' looks like a small subsection, but is actually half the document. It should probably be moved into a 'how to deal with warnings' article (not under guidelines), with a shorter, more general guideline on this page that would link to the article.
Agreed - It has just 'growded like Topsy':
it needs an editor, guided by feedback, to keep it in some short of shape.
(But that should not stop others making changes - still a wiki).
Most people are polite enough to say "I've amplified/changed/deleted the section on ... - is this OK"?
Paul, would you like to take care of separating the Managing Warnings from Compilers section?
OK - that will teach me to keep my mouth shut! I'll put it on my TODO list. Paul --- Paul A. Bristow Prizet Farmhouse Kendal, UK LA8 8AB +44 1539 561830, mobile +44 7714330204 pbristow@hetp.u-net.com
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Daniel James Sent: Friday, March 26, 2010 1:18 PM To: boost@lists.boost.org Subject: Re: [boost] Guidelines on wiki
In the contents, 'Managing Warnings from Compilers' looks like a small subsection, but is actually half the document. It should probably be moved into a 'how to deal with warnings' article (not under guidelines), with a shorter, more general guideline on this page that would link to the article.
Paul, would you like to take care of separating the Managing Warnings from Compilers section?
OK - that will teach me to keep my mouth shut!
I'll put it on my TODO list.
Done.
Paul
--- Paul A. Bristow Prizet Farmhouse Kendal, UK LA8 8AB +44 1539 561830, mobile +44 7714330204 pbristow@hetp.u-net.com
participants (5)
-
Daniel James -
Daniel James -
Paul A. Bristow -
Robert Ramey -
vicente.botet