Обсуждение: Website Redo Kick Off

It has been for sometime the desire to redo the website. The main goals
being:

1. Make the Site Easier To Maintain.
2. Allow Others to Contribute/Manage the Updates.

I have offered to perform the work and have done some reviewing of the
past history of the discussions on this subject. In so doing I have taken
notes on possible options and done some preliminary research in potential
solutions. A General background is in order so that I can try to direct
the feedback/discussion to the desired goals stated.

History:

The website as been in existence since the early 2000s. An update for
the site occurred in around 2004 by Kris Jurka to Apache Forest. Forest
is a scripting engine that generates static pages that are then transfered
to the web server. That current mechanism is still in place to update
the website, but Forest is no longer being maintained as a project it
seems.  Forest also does not seem to be conducive to the desire goal
#2 above. The web server host does not support CMS and it seems to be
desired to continue along the lines of a scripting engine to generate
static webpages for the redo.

Help: (Narrow Options)

* If you know of a scripting engine that is not listed below please reply.

* If you have experience with one listed please comment, seems good/not
   so good and the language used if possible.

* If you have a few minutes please consider randomly selecting one on the
   list to review so that you could let us know if it may be a good solution.

Thank you.
danap, Dana M. Proctor

Hyde:
http://hyde.github.io/

Sculpin:
http://sculpin.io/

Phrozn:
http://www.phrozn.info/en/

Bonsai:
http://tinytree.info/

Winter Smith:
http://jnordberg.github.io/wintersmith/

Pie Crust:
http://bolt80.com/piecrust/

Jekyll:
http://jekyllrb.com/

Middle Man:
http://middlemanapp.com/

Nanoc:
http://nanoc.ws/

Stasis:
http://stasis.me/

ToTo
https://github.com/cloudhead/toto

Staticmatic
https://github.com/staticmatic/staticmatic

Webgen
https://github.com/gettalong/webgen

Movable Type
http://www.movabletype.org/download.html

Pelican
http://docs.getpelican.com/en/3.2/

On 10.07.2013 18:54, dmp wrote:
> It has been for sometime the desire to redo the website. The main goals
> being:
>
> 1. Make the Site Easier To Maintain.
> 2. Allow Others to Contribute/Manage the Updates.
>
> I have offered to perform the work and have done some reviewing of the
> past history of the discussions on this subject.

Hooray!

> Help: (Narrow Options)
>
> * If you know of a scripting engine that is not listed below please reply.
>
> * If you have experience with one listed please comment, seems good/not
> so good and the language used if possible.
>
> * If you have a few minutes please consider randomly selecting one on the
> list to review so that you could let us know if it may be a good solution.

I don't expect very frequent updates, or very many people updating it,
so I think the most important criteria is low barrier to maintain it. It
should be easy for anyone to jump in and submit changes. It's probably
good to pick something that's popular, even if that isn't the best
alternative otherwise, just to make sure the tool is widely available in
distributions that people use and that there are people out there with
experience with it.

I reworked the ODBC driver's website recently. I just did it with plain
HTML files, stored in a git repository. That was very simple. I don't
necessarily recommend you to do it that way, but it works. If you come
up with something better, I'll probably copy that to psqlodbc :-).

(I don't personally have any opinion on which of the static site
generators to use, I haven't used any of them. I'm sure they're all good
enough for our needs)

Pretty much anything is better than the current situation, so +1 to
whatever you decide :-).

- Heikki

Heikki Linnakangas wrote:
> On 10.07.2013 18:54, dmp wrote:
>> It has been for sometime the desire to redo the website. The main goals
>> being:
>>
>> 1. Make the Site Easier To Maintain.
>> 2. Allow Others to Contribute/Manage the Updates.
>>
>> I have offered to perform the work and have done some reviewing of the
>> past history of the discussions on this subject.
>
> Hooray!
>
>> Help: (Narrow Options)
>>
>> * If you know of a scripting engine that is not listed below please
>> reply.
>>
>> * If you have experience with one listed please comment, seems good/not
>> so good and the language used if possible.
>>
>> * If you have a few minutes please consider randomly selecting one on the
>> list to review so that you could let us know if it may be a good
>> solution.
>
> I don't expect very frequent updates, or very many people updating it,
> so I think the most important criteria is low barrier to maintain it.

So two goals that are not just quantitative, but with priority, #1 over #2
as you deduce.

> It should be easy for anyone to jump in and submit changes. It's probably
> good to pick something that's popular, even if that isn't the best
> alternative otherwise, just to make sure the tool is widely available in
> distributions that people use and that there are people out there with
> experience with it.
>
> I reworked the ODBC driver's website recently. I just did it with plain
> HTML files, stored in a git repository. That was very simple. I don't
> necessarily recommend you to do it that way, but it works. If you come
> up with something better, I'll probably copy that to psqlodbc :-).
>
> (I don't personally have any opinion on which of the static site
> generators to use, I haven't used any of them. I'm sure they're all good
> enough for our needs)

Dave, indicated to me the update to the ODBC driver site and I have reviewed.

I would envision that files used for generation could be in git, so therefore
helping with goal #2.

I'm not so confident that anyone of them would probably meet the needs of the
project. Heikki, perhaps you could take a few minutes to review one of them. My
cursorly review of some of them indicated that they are more oriented toward
a single page blog, rather then a multi-menued site.

In asking others to review I do not mean to install and try just look over
the documentation/information and if a sample site(s) have been indicated
visit.

danap.

>
> Pretty much anything is better than the current situation, so +1 to
> whatever you decide :-).
>
> - Heikki
>

I like the workflow that Jekyll promotes.  Documentation updates can be submitted in the same way as code updates (as
pullrequests) and the Markdown syntax is easy to learn / use.  There is low perceived friction to updating the
documentation,which is good to drive contributions. 

I have only used it in the context of GitHub (i.e. I cannot vouch that maintaining it outside of the context is as easy
asthey claim, nor do I have any reason to believe it isn't) but I think it deserves a close look. 

+1 on too many choices, unless there are volunteers to go through all of them we can probably just look at the five
"mostpopular" or something. 

On Jul 10, 2013, at 3:54 PM, Dave Cramer <pg@fastcrypt.com> wrote:

> Dana,
>
> I think you gave us too many choices!
>
> If I had to choose it would be jekyll only because of the inertia from the github folks
>
>
> Dave Cramer
>
> dave.cramer(at)credativ(dot)ca
> http://www.credativ.ca
>
>
> On Wed, Jul 10, 2013 at 3:29 PM, Stephen Nelson <stephen@eccostudio.com> wrote:
> Echoing what Heikki said, I personally haven't used any of the site generators mentioned. However the solution does
needto be a simple git checkout and with minimal dependencies you can make updates. I've tried to get the current site
docgenerated a few times without much luck in generating some of the pages. So definitely simplicity rules. 
>
> I believe github uses Jekyll and it supports the markdown syntax that is easy to understand and used on github. But I
haven'tused it so can't vouch for its ease of use or popularity. 
>
> Cheers,
>
> Stephen
>

Well I did start off with the top ten, the ones listed first from a site,
but then added a few more just to make it confusing. I did not think them
as choices at this point. Just a kick off hopefully in the right direction.

Seems though you guys are narrowing the list for me. I will give it a few
more days for feedback before I start digging into just a few. Your guy's
feedback is appreciated and should save me some time researching.

Thank you,
danap.

Dave Cramer wrote:
> Dana,
>
> I think you gave us too many choices!
>
> If I had to choose it would be jekyll only because of the inertia from
> the github folks
>
>
> Dave Cramer
>
> dave.cramer(at)credativ(dot)ca
> http://www.credativ.ca

> * If you have experience with one listed please comment, seems good/not
>   so good and the language used if possible.

> Pelican
> http://docs.getpelican.com/en/3.2/

Pelican's main usage seems to be for blogs but it can also generate
regular pages. I recently converted my personal blog to pelican. I went
with Markdown as the markup language because I'm already quite familiar
with it from github.

The use of pelican is dead simple. If you stick to the suggested
directory structure it's all about handling files and running "make
html" to generate the output which is then published to the web server.

I chose pelican because it's python based. Python's "virtualenv" tool
allows to set up all the required libraries in a local folder - I wasn't
able to find a 1:1 equivalent for the ruby based frameworks.

-dirk

Thanks dirk for the feedback on pelican.

danap.

Dirk Olmes wrote:
>> * If you have experience with one listed please comment, seems good/not
>>    so good and the language used if possible.
>
>> Pelican
>> http://docs.getpelican.com/en/3.2/
>
> Pelican's main usage seems to be for blogs but it can also generate
> regular pages. I recently converted my personal blog to pelican. I went
> with Markdown as the markup language because I'm already quite familiar
> with it from github.
>
> The use of pelican is dead simple. If you stick to the suggested
> directory structure it's all about handling files and running "make
> html" to generate the output which is then published to the web server.
>
> I chose pelican because it's python based. Python's "virtualenv" tool
> allows to set up all the required libraries in a local folder - I wasn't
> able to find a 1:1 equivalent for the ruby based frameworks.
>
> -dirk

Well since I'm not a Maven expert I can not address the first question
perhaps someone else, but it has generally been determined that a static
site generator is desired from past discussions.

It makes sense since the existing tool Apache Forest has worked well over
the years and apparently made updating the site not require a lot of
editing.

Perhaps you could outline a XHTML simple example that I could examine
to understand the process of updating the site with new content. I'm
willing to look at this possible solution in conjunction with my existing
review of scripting tools. If it seems simple and straight I would be
prepared to advocate with you on your position.

As an update I will be completing the review of tools this weekend and
selecting a few for trial early next week. A list of my notes on the tools
and the location I will be testing/building the new site is at the URL
below.

http://pgjdbc.ourbigsky.com/

danap.

Posted on slashdot: 7/12/2013 PostgreSQL vs Oracle. Seemed positive
                     for PostgreSQL.

http://developers.slashdot.org/story/13/07/13/0018224/ask-slashdot-is-postgres-on-par-with-oracle/


Kevin Carr wrote:
> What about just using maven and adding the static pages in the build
> process?  That way it can automatically update the current version, and
> various other information from the project file?
>
> Just a thought.  I don't see there being too much to the site, so plain
> xhtml would be feasible as well, without a generator.  Once created, a
> properly stylesheet enabled xhtml is easy to maintain.

Over the weekend I completed the review of all the scripting tools documented
for generating static sites. Per the group's request I narrowed the field down
to the ones listed below. Narrowing was first based on currency of project
files, then other things like documentation. Since I'm new to these tools I'm
sure the narrowing was much less knowledge based, but rather by impression.

I will begin installing and trying the tools now. At the top of this, only
by coincidence, was Jekyll it had the most responses. Webgen seems to have been
a stable in this area for awhile and was quoted by many of the other tools.
Apache ASF is a CMS, but was mentioned in the discussion and may be viable
for the website generation I do not know. I will investigate further. I came
across Twitter Bootstrap and it impressed me because it seemed simple and had
example templates for various sites.

danap.

Tools:

===================
Jekyll: (2013)
http://jekyllrb.com/
ruby

===================
Webgen: (2013)
https://github.com/gettalong/webgen
http://webgen.rubyforge.org/documentation/
ruby

====================
Apache ASF Content Management System: (In Use since 2010)
https://svn.apache.org/repos/infra/websites/cms/ (subversion)
http://www.apache.org/dev/cms.html (Info)

=====================
Twitter Bootstrap (2013)
http://twitter.github.io/bootstrap/
javascript

i can program in Ruby if need be.

Thanks Tom for the feedback. The year is latest activity on the project or
release. I will take twitter off the list. I thought it looked liking a
scripting/publshing tool.

danap.

Tom Dunstan wrote:
> On 16 July 2013 02:33, dmp <danap@ttc-cmc.net
> <mailto:danap@ttc-cmc.net>> wrote:
>
>     Over the weekend I completed the review of all the scripting tools
>     documented
>     for generating static sites.
>
>
> Not sure what the years next to each of the listed items are supposed to
> be, but I can guarantee that Jekyll and twitter bootstrap have been
> around since at least 2011, as I was using both of them then.
> Also, twitter bootstrap is a set of nice CSS defaults and a few dynamic
> components, it's not a publishing tool. But not a bad place to start for
> base CSS for a site.
>
> Cheers
>
> Tom

In the last week I have evaluated the reduced list of tools for creating
the new website by installing, using, and reviewing the documentation. A
selection has been made to use Jekyll.

The reason largely based on the two goals outlined in the initial thread
and user responses.

Goals:

1. Make the Site Easier To Maintain.
2. Allow Others to Contribute/Manage the Updates.

Jekyll met those requirements better than the other options, Twitter
Bootstrap was removed, because it is not a site generation tool as
pointed out by feedback.

The plan is to change the site to match the existing style of the
postgresql.org site. As I begin this process of creating the scripted
site I will post updates for review to:

http://pgjdbc.ourbigsky.com/

danap

dmp wrote:
> Over the weekend I completed the review of all the scripting tools
> documented
> for generating static sites. Per the group's request I narrowed the
> field down
> to the ones listed below. Narrowing was first based on currency of project
> files, then other things like documentation. Since I'm new to these
> tools I'm
> sure the narrowing was much less knowledge based, but rather by impression.
>
> I will begin installing and trying the tools now. At the top of this, only
> by coincidence, was Jekyll it had the most responses. Webgen seems to
> have been
> a stable in this area for awhile and was quoted by many of the other tools.
> Apache ASF is a CMS, but was mentioned in the discussion and may be viable
> for the website generation I do not know. I will investigate further. I
> came
> across Twitter Bootstrap and it impressed me because it seemed simple
> and had
> example templates for various sites.
>
> danap.
>
> Tools:
>
> ===================
> Jekyll: (2013)
> http://jekyllrb.com/
> ruby
>
> ===================
> Webgen: (2013)
> https://github.com/gettalong/webgen
> http://webgen.rubyforge.org/documentation/
> ruby
>
> ====================
> Apache ASF Content Management System: (In Use since 2010)
> https://svn.apache.org/repos/infra/websites/cms/ (subversion)
> http://www.apache.org/dev/cms.html (Info)
>
> =====================
> Twitter Bootstrap (2013)
> http://twitter.github.io/bootstrap/
> javascript
>
>

Dave,

I'm sure that postings will be required, because some questions may be
posed to the list for response to inclusion or exclusion of some parts
of the HTML. For example there appears to be a number of javascripts in
the pages.

Also I guess I can ask now, why is there pages for public & private
APIs?

I found on my project that through web analysis very few people
were actually accessing the API docs, so I removed them since they
were already available with the download. I'm not advocating this
in pgjdbc's case, by why two?

danap.

Dave Cramer wrote:
> Hi Dana,
>
> This is awesome! Keep us posted.
>
> Dave Cramer
>
> dave.cramer(at)credativ(dot)ca
> http://www.credativ.ca
>
>
> On Wed, Jul 24, 2013 at 2:24 PM, dmp <danap@ttc-cmc.net
> <mailto:danap@ttc-cmc.net>> wrote:
>
>     In the last week I have evaluated the reduced list of tools for creating
>     the new website by installing, using, and reviewing the documentation. A
>     selection has been made to use Jekyll.
>
>     The reason largely based on the two goals outlined in the initial thread
>     and user responses.
>
>     Goals:
>
>
>     1. Make the Site Easier To Maintain.
>     2. Allow Others to Contribute/Manage the Updates.
>
>     Jekyll met those requirements better than the other options, Twitter
>     Bootstrap was removed, because it is not a site generation tool as
>     pointed out by feedback.
>
>     The plan is to change the site to match the existing style of the
>     postgresql.org <http://postgresql.org> site. As I begin this process
>     of creating the scripted
>     site I will post updates for review to:
>
>     http://pgjdbc.ourbigsky.com/
>
>     danap

On Wed, 24 Jul 2013, dmp wrote:

> Also I guess I can ask now, why is there pages for public & private
> APIs?
>

The public API is what we expose to end user applications and try to keep
stable.  Anything that is going under the JDBC API to use PG specific
functionality should be using the public API.

The private API is more for driver developers/users to see how things are
structured internally.

Kris Jurka

I have started to put together the structure of the website for Jekyll.

I would like to modify the menu system to more closely resemble the
postgresql.org site and therefore probably move some things around.

1. Propose: (Top Menu)

Home | Download | Documentation | Community | Development

2. Currently the existing site is self contained. This fits nicely
    with using Jekyll and allows others to contribute. I would
    like to keep it this way, which implies no linkage to the
    main site, postresql.org, with style, script, & image files.

http://pgjdbc.ourbigsky.com/

danap