Mailing List Archive

Documentation updates
When I first looked at Bricolage, I was a little put-off by the
documentation. The wiki, for example, has quite a few dead links, it's
fragmented, and I was hoping to see some more 'how to' type articles.

This was one of the reasons that made me look for an alternative CMS. I
came back to Bricolage after being unable to find what I wanted
elsewhere. I'm glad I did - it is clearly a powerful system, and I'm
enjoying using it.

I'd therefore like to start updating the wiki. Some ideas are:

* Remove dead links

* Create fresh links for existing content that is currently hard to find
(such as the template examples in the developer's area on GitHub)

* Create a new section for Bricolage 2.0 and include links to relevant
documentation (such as a suggested order of the API docs for beginners),
'how to' or cookbook style articles, and template examples

Other suggestions are welcome. Can anyone provide links to orphaned docs?

What's the etiquette for this? Should I go ahead and start new docs,
and gain list approval before removing old links?

As a Bricolage beginner, it would be good if my work was vetted by other
more experienced users. I'm also working with Template Toolkit, so
Mason translations might be useful too. I can post messages on this
list to any new content.


Regards,

Mike
Re: Documentation updates [ In reply to ]
On May 16, 2011, at 12:09 AM, Mike Raynham wrote:

> When I first looked at Bricolage, I was a little put-off by the documentation. The wiki, for example, has quite a few dead links, it's fragmented, and I was hoping to see some more 'how to' type articles.
>
> This was one of the reasons that made me look for an alternative CMS. I came back to Bricolage after being unable to find what I wanted elsewhere. I'm glad I did - it is clearly a powerful system, and I'm enjoying using it.
>
> I'd therefore like to start updating the wiki. Some ideas are:

Mike++

> * Remove dead links
>
> * Create fresh links for existing content that is currently hard to find (such as the template examples in the developer's area on GitHub)
>
> * Create a new section for Bricolage 2.0 and include links to relevant documentation (such as a suggested order of the API docs for beginners), 'how to' or cookbook style articles, and template examples

That sounds good.

> Other suggestions are welcome. Can anyone provide links to orphaned docs?

A few howtos were published on the main site, though Phillip might have moved them to the wiki, I'm not sure.

> What's the etiquette for this? Should I go ahead and start new docs, and gain list approval before removing old links?

JFDI.

> As a Bricolage beginner, it would be good if my work was vetted by other more experienced users. I'm also working with Template Toolkit, so Mason translations might be useful too. I can post messages on this list to any new content.

That'd be great. I think I'm subscribed to a feed to notify me when wiki pages are modified, so I'll try to diff stuff when you check in changes.

Thanks!

David
Re: Documentation updates [ In reply to ]
Hi David,

Thanks. I've made a start on a Bricolage 2.0 section. Most of the
stuff in there is just links to existing articles and documentation.
I'll be adding more as I learn more.

I'm working through re-creating an existing website, and will take notes
as I go. If I find that I need to ask questions on the mailing list, or
need to do other research to figure something out, I'll try to add it to
the wiki.

Once I've done that, I hope (time permitting) to write a guide to
creating a simple website from start to finish using Bricolage. I don't
work with the large multi-user sites that I suspect many Bricolage users
do, but hopefully even a simple site will cover many of the basics.


Regards,

Mike

On 16/05/11 17:28, David E. Wheeler wrote:
> On May 16, 2011, at 12:09 AM, Mike Raynham wrote:
>
>> When I first looked at Bricolage, I was a little put-off by the documentation. The wiki, for example, has quite a few dead links, it's fragmented, and I was hoping to see some more 'how to' type articles.
>>
>> This was one of the reasons that made me look for an alternative CMS. I came back to Bricolage after being unable to find what I wanted elsewhere. I'm glad I did - it is clearly a powerful system, and I'm enjoying using it.
>>
>> I'd therefore like to start updating the wiki. Some ideas are:
>
> Mike++
>
>> * Remove dead links
>>
>> * Create fresh links for existing content that is currently hard to find (such as the template examples in the developer's area on GitHub)
>>
>> * Create a new section for Bricolage 2.0 and include links to relevant documentation (such as a suggested order of the API docs for beginners), 'how to' or cookbook style articles, and template examples
>
> That sounds good.
>
>> Other suggestions are welcome. Can anyone provide links to orphaned docs?
>
> A few howtos were published on the main site, though Phillip might have moved them to the wiki, I'm not sure.
>
>> What's the etiquette for this? Should I go ahead and start new docs, and gain list approval before removing old links?
>
> JFDI.
>
>> As a Bricolage beginner, it would be good if my work was vetted by other more experienced users. I'm also working with Template Toolkit, so Mason translations might be useful too. I can post messages on this list to any new content.
>
> That'd be great. I think I'm subscribed to a feed to notify me when wiki pages are modified, so I'll try to diff stuff when you check in changes.
>
> Thanks!
>
> David
>
>
Re: Documentation updates [ In reply to ]
On May 17, 2011, at 1:55 AM, Mike Raynham wrote:

> Hi David,
>
> Thanks. I've made a start on a Bricolage 2.0 section. Most of the stuff in there is just links to existing articles and documentation. I'll be adding more as I learn more.
>
> I'm working through re-creating an existing website, and will take notes as I go. If I find that I need to ask questions on the mailing list, or need to do other research to figure something out, I'll try to add it to the wiki.

Awesome, thank you!

> Once I've done that, I hope (time permitting) to write a guide to creating a simple website from start to finish using Bricolage. I don't work with the large multi-user sites that I suspect many Bricolage users do, but hopefully even a simple site will cover many of the basics.

Absolutely, that would be a very welcome contribution.

Best,

David
Re: Documentation updates [ In reply to ]
I've been working on a few documents in the wiki, and have just
completed "Installing Bricolage 2.0.1 on Ubuntu 10.04 LTS (Lucid Lynx)":

http://tinyurl.com/6kpvtq5

I'm not a Bricolage expert or a sysadmin. I'm quite new to PostgreSQL
too. So it would be good if someone more knowledgeable could have a
look at it, just to make sure I've not done anything stupid.

I have tried to include a few 'non standard' options, such as using
local::lib to contain all the Perl modules, running the process under
its own user, and using a non-default installation directory.

I've updated it a few times, and have run through the whole process
repeatedly - it works for me so far.



Regards,

Mike
Re: Documentation updates [ In reply to ]
Hi Mike,

> I've been working on a few documents in the wiki, and have just
> completed "Installing Bricolage 2.0.1 on Ubuntu 10.04 LTS (Lucid Lynx)":

Very cool! One suggestion to make it easier to maintain, maybe just
recommend installing Bundle::Bricolage or Bundle::BricolagePlus rather
then the individual modules?

Cheers,

Alex

--
Alex Krohn <alex@gt.net>
Re: Documentation updates [ In reply to ]
Hi Alex,

Yes, that's a good idea. I ended up installing the modules manually
because I ran into a few dependency issues when I let the Bricolage
installer install the modules. However, now that I have those
dependencies sorted out, both the Bricolage installer and the Bundle::*
packages should work. Having said that, I haven't yet managed to get
Apache2::SizeLimit installed - but I didn't try very hard :-)

I'll test it out when I get chance, and add it to the wiki.



Regards,

Mike


On 03/06/11 16:05, Alex Krohn wrote:
> Hi Mike,
>
>> I've been working on a few documents in the wiki, and have just
>> completed "Installing Bricolage 2.0.1 on Ubuntu 10.04 LTS (Lucid Lynx)":
>
> Very cool! One suggestion to make it easier to maintain, maybe just
> recommend installing Bundle::Bricolage or Bundle::BricolagePlus rather
> then the individual modules?
>
> Cheers,
>
> Alex
>
> --
> Alex Krohn<alex@gt.net>
Re: Documentation updates [ In reply to ]
On Jun 3, 2011, at 7:16 AM, Mike Raynham wrote:

> I've been working on a few documents in the wiki, and have just completed "Installing Bricolage 2.0.1 on Ubuntu 10.04 LTS (Lucid Lynx)":
>
> http://tinyurl.com/6kpvtq5
>
> I'm not a Bricolage expert or a sysadmin. I'm quite new to PostgreSQL too. So it would be good if someone more knowledgeable could have a look at it, just to make sure I've not done anything stupid.

Great work! And a lot of work, too. Thank you for taking the time to do this.

Two suggestions re: PostgreSQL configuration:

1. Maybe link to http://www.depesz.com/index.php/2007/10/04/ident/ for those interested in why ident is problematic.
2. Link to http://www.bricolagecms.org/docs/current/api/Bric::DBA#Tuning for information on tuning PostgreSQL for your hardware.

Best,

David
Re: Documentation updates [ In reply to ]
On 03/06/11 17:31, David E. Wheeler wrote:
> On Jun 3, 2011, at 7:16 AM, Mike Raynham wrote:
>
>> I've been working on a few documents in the wiki, and have just completed "Installing Bricolage 2.0.1 on Ubuntu 10.04 LTS (Lucid Lynx)":
>>
>> http://tinyurl.com/6kpvtq5
>>
>> I'm not a Bricolage expert or a sysadmin. I'm quite new to PostgreSQL too. So it would be good if someone more knowledgeable could have a look at it, just to make sure I've not done anything stupid.
>
> Great work! And a lot of work, too. Thank you for taking the time to do this.

No problem - it's just s souped up version of the notes that I created
during the install. Thanks for taking the time to create Bricolage!

>
> Two suggestions re: PostgreSQL configuration:
>
> 1. Maybe link to http://www.depesz.com/index.php/2007/10/04/ident/ for those interested in why ident is problematic.
> 2. Link to http://www.bricolagecms.org/docs/current/api/Bric::DBA#Tuning for information on tuning PostgreSQL for your hardware.

Great links, thanks. I'll read the articles, and add the links to the wiki.
Re: Documentation updates [ In reply to ]
On 03/06/11 16:05, Alex Krohn wrote:
> Hi Mike,
>
>> I've been working on a few documents in the wiki, and have just
>> completed "Installing Bricolage 2.0.1 on Ubuntu 10.04 LTS (Lucid Lynx)":
>
> Very cool! One suggestion to make it easier to maintain, maybe just
> recommend installing Bundle::Bricolage or Bundle::BricolagePlus rather
> then the individual modules?

I attempted the Bundle::Bricolage installation this morning, but it
tries to install mod_perl, instead of mod_perl2, so unless I'm missing
something, it's only suitable for use with Apache 1.x, not Apache 2.x.

However, this lead me to notice that I've installed the following Perl
modules using Ubuntu packages, instead of via CPAN:

libapache2-mod-apreq2
libapache2-mod-perl2
libapache2-request-perl

That kinda defeats the object of installing the required CPAN modules in
a self-contained extlib directory. However, installing mod_perl2 via
CPAN is proving to be quite tricky, so for now at least, the simple
'cheating' approach will have to do...

>
> Cheers,
>
> Alex
>
> --
> Alex Krohn<alex@gt.net>

Regards,

Mike
Re: Documentation updates [ In reply to ]
On Jun 4, 2011, at 3:38 AM, Mike Raynham wrote:

> I attempted the Bundle::Bricolage installation this morning, but it tries to install mod_perl, instead of mod_perl2, so unless I'm missing something, it's only suitable for use with Apache 1.x, not Apache 2.x.

Bah! I should rip mod_perl out of the bundle.

> However, this lead me to notice that I've installed the following Perl modules using Ubuntu packages, instead of via CPAN:
>
> libapache2-mod-apreq2
> libapache2-mod-perl2
> libapache2-request-perl
>
> That kinda defeats the object of installing the required CPAN modules in a self-contained extlib directory. However, installing mod_perl2 via CPAN is proving to be quite tricky, so for now at least, the simple 'cheating' approach will have to do...

I wouldn't install mod_perl via CPAN, ever. Just doesn't work very well.

Best,

David