Documentation update

[Jim Fulton]

I've made quite a bit of progress and I can see the light at the end of the tunnel.  Much thanks for the excellent reviews I've gotten so far!

Documentation that's been reviewed and merged to master is live at:

  http://docs.buildout.org

There are several documentation PRs awaiting review:

  https://github.com/buildout/buildout/labels/Needs%20Review

Once these reviews are done, I think we can announce the docs.

There's a todo list:

 https://github.com/buildout/buildout/blob/new-doc-integration/doc/todo.txt

of remaining docs to reach parity with what we have now (which is pretty complete).

Many of the items on the to-do list are small. (None are big) I can knock them out in the next week or so, I think, but I need reviewers. :)

Jim

--

Jim Fulton
http://jimfulton.info

[Dylan Jay]

I’m a big fan of a simple example on the first page ala Flask - http://flask.pocoo.org.
I don’t mean removing what you already have, or changing the getting started section.
But perhaps a sidebar or section on the current frontpage which shows the most typical yet minimal buildout? Just so that there is some concrete context to the abstract ideas of Repeatability, Componentization, Automation
To me this would be a collective.recipe.template + zc.recipe.egg + some variable substitution. Maybe not the best application but this is what I showed first in this talk - https://www.slideshare.net/djay/buildout-how-to-maintain-big-app-stacks-without-losing-your-mind.

Perhaps something like installing flask + a config that lets you run it on a certain port?

Just an idea. Feel free to ignore.

> --
> You received this message because you are subscribed to the Google Groups "Buildout Development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to buildout-develop...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[Jim Fulton]

On Tue, Feb 28, 2017 at 1:06 AM, Dylan Jay <dj...@pretaweb.com> wrote:

I’m a big fan of a simple example on the first page ala Flask - http://flask.pocoo.org.

Hello world for something like flask is a no-brainer.

(http://bobo.readthedocs.io :-))

 

I don’t mean removing what you already have, or changing the getting started section.
But perhaps a sidebar or section on the current frontpage which shows the most typical yet minimal buildout? Just so that there is some concrete context to the abstract ideas of Repeatability, Componentization, Automation
To me this would be a collective.recipe.template + zc.recipe.egg + some variable substitution. Maybe not the best application but this is what I showed first in this talk - https://www.slideshare.net/djay/buildout-how-to-maintain-big-app-stacks-without-losing-your-mind.

Perhaps something like installing flask + a config that lets you run it on a certain port?

I'm open to examples.  It's hard to come up with a meaningful buildout example that's the equivalent of hello world. 

Maybe we should just create a print recipe and:

  [buildout]

  parts = greeting

  who = world

  [greeting]

  recipe = buildout.print

  text = Hello ${buildout:who}

This illustrates using a recipe and substitution and could show running as both:

  buildout

and

  buildout who=guido

Just an idea. Feel free to ignore.

Ideas are good. :)

 Jim

> On 27 Feb 2017, at 9:41 pm, Jim Fulton <j...@jimfulton.info> wrote:
>
>
> I've made quite a bit of progress and I can see the light at the end of the tunnel.  Much thanks for the excellent reviews I've gotten so far!
>
> Documentation that's been reviewed and merged to master is live at:
>
>   http://docs.buildout.org
>
> There are several documentation PRs awaiting review:
>
>   https://github.com/buildout/buildout/labels/Needs%20Review
>
> Once these reviews are done, I think we can announce the docs.
>
> There's a todo list:
>
>  https://github.com/buildout/buildout/blob/new-doc-integration/doc/todo.txt
>
> of remaining docs to reach parity with what we have now (which is pretty complete).
>
> Many of the items on the to-do list are small. (None are big) I can knock them out in the next week or so, I think, but I need reviewers. :)
>
> Jim
>
> --
> Jim Fulton
> http://jimfulton.info
>

> --
> You received this message because you are subscribed to the Google Groups "Buildout Development" group.

> To unsubscribe from this group and stop receiving emails from it, send an email to buildout-development+unsubscrib...@googlegroups.com.

> For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Buildout Development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to buildout-development+unsubscrib...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Dylan Jay]

> On 3 Mar 2017, at 12:15 am, Jim Fulton <j...@jimfulton.info> wrote:
>
>
>
> On Tue, Feb 28, 2017 at 1:06 AM, Dylan Jay <dj...@pretaweb.com> wrote:
> I’m a big fan of a simple example on the first page ala Flask - http://flask.pocoo.org.
>
> Hello world for something like flask is a no-brainer.
> (http://bobo.readthedocs.io :-))
>
> I don’t mean removing what you already have, or changing the getting started section.
> But perhaps a sidebar or section on the current frontpage which shows the most typical yet minimal buildout? Just so that there is some concrete context to the abstract ideas of Repeatability, Componentization, Automation
> To me this would be a collective.recipe.template + zc.recipe.egg + some variable substitution. Maybe not the best application but this is what I showed first in this talk - https://www.slideshare.net/djay/buildout-how-to-maintain-big-app-stacks-without-losing-your-mind.
>
> Perhaps something like installing flask + a config that lets you run it on a certain port?
>
> I'm open to examples. It's hard to come up with a meaningful buildout example that's the equivalent of hello world.
>
> Maybe we should just create a print recipe and:
>
> [buildout]
> parts = greeting
> who = world
>
> [greeting]
> recipe = buildout.print
> text = Hello ${buildout:who}
>
> This illustrates using a recipe and substitution and could show running as both:
>
> buildout
>
> and
>
> buildout who=guido
>
> Just an idea. Feel free to ignore.
>
> Ideas are good. :)

Yours looks simple which is good.
However it perhaps makes buildout look like its more an execution environment rather something that you use to gaffer tap others things togeather which you then run?

However the simplest example I could think of is that simple :(

[buildout]
parts = greeting
who = world

[greeting]

recipe = zc.recipe.egg
eggs = pyfiglet
initialization =
from pyfiglet import Figlet
f = Figlet(font=‘slant')
main = lambda: f.renderText("hello "+"""${buildout:who}""")
entry-points = greeting=__main__:main


then you run bin/greeting

>
> Jim
>
>
>
> > On 27 Feb 2017, at 9:41 pm, Jim Fulton <j...@jimfulton.info> wrote:
> >
> >
> > I've made quite a bit of progress and I can see the light at the end of the tunnel. Much thanks for the excellent reviews I've gotten so far!
> >
> > Documentation that's been reviewed and merged to master is live at:
> >
> > http://docs.buildout.org
> >
> > There are several documentation PRs awaiting review:
> >
> > https://github.com/buildout/buildout/labels/Needs%20Review
> >
> > Once these reviews are done, I think we can announce the docs.
> >
> > There's a todo list:
> >
> > https://github.com/buildout/buildout/blob/new-doc-integration/doc/todo.txt
> >
> > of remaining docs to reach parity with what we have now (which is pretty complete).
> >
> > Many of the items on the to-do list are small. (None are big) I can knock them out in the next week or so, I think, but I need reviewers. :)
> >
> > Jim
> >
> > --
> > Jim Fulton
> > http://jimfulton.info
> >
> > --
> > You received this message because you are subscribed to the Google Groups "Buildout Development" group.

> > To unsubscribe from this group and stop receiving emails from it, send an email to buildout-develop...@googlegroups.com.

> > For more options, visit https://groups.google.com/d/optout.
>
> --
> You received this message because you are subscribed to the Google Groups "Buildout Development" group.

> To unsubscribe from this group and stop receiving emails from it, send an email to buildout-develop...@googlegroups.com.

> For more options, visit https://groups.google.com/d/optout.
>
>
>
> --
> Jim Fulton
> http://jimfulton.info
>

> --
> You received this message because you are subscribed to the Google Groups "Buildout Development" group.

> To unsubscribe from this group and stop receiving emails from it, send an email to buildout-develop...@googlegroups.com.

[Dylan Jay]

Your buildout.print idea is better, esp if a) buildout.print already existed on pypi. b) it created a bin/greeting script that did the output rather than outputting during buildout.

One other idea I had was writing an single html page with a greeting and building a simple http server on a buildout specified port to display that page.
But again I can’t think how to make it look simple enough.

[Marius Gedminas]

On Tue, Mar 07, 2017 at 10:36:50AM +0700, Dylan Jay wrote:
> > On 4 Mar 2017, at 12:17 pm, Dylan Jay <dj...@pretaweb.com> wrote:
> >> On 3 Mar 2017, at 12:15 am, Jim Fulton <j...@jimfulton.info> wrote:
> >> On Tue, Feb 28, 2017 at 1:06 AM, Dylan Jay <dj...@pretaweb.com> wrote:
> >> I’m a big fan of a simple example on the first page ala Flask - http://flask.pocoo.org.
> >>
> >> Hello world for something like flask is a no-brainer.
> >> (http://bobo.readthedocs.io :-))
> >>
> >> I don’t mean removing what you already have, or changing the getting started section.
> >> But perhaps a sidebar or section on the current frontpage which shows the most typical yet minimal buildout? Just so that there is some concrete context to the abstract ideas of Repeatability, Componentization, Automation
> >> To me this would be a collective.recipe.template + zc.recipe.egg + some variable substitution. Maybe not the best application but this is what I showed first in this talk - https://www.slideshare.net/djay/buildout-how-to-maintain-big-app-stacks-without-losing-your-mind.
> >>
> >> Perhaps something like installing flask + a config that lets you run it on a certain port?

I think it would be nice to have something small that lets the user
achieve something useful, e.g. install Django using djangorecipe or
something.

Marius Gedminas
--
My opinions may have changed, but not the fact that I'm right!

[Jim Fulton]

The they have a working web server (serving the contents of the buildout directory) halfway through the getting-started section. <shrug>

Jim

[Dylan Jay]

> On 7 Mar 2017, at 9:09 pm, Jim Fulton <j...@jimfulton.info> wrote:
>
> > I think it would be nice to have something small that lets the user
> > achieve something useful, e.g. install Django using djangorecipe or
> > something.
>
> The they have a working web server (serving the contents of the buildout directory) halfway through the getting-started section. <shrug>

Sure. It’s silly and its marketing but people learn/are motivated in different ways. Seeing a concrete simple example on the front page will help people make the next click read getting started. Especially if its simple and self explanatory. At the moment the front page is heavy on abstract ideas. I’ve always been a fan the ideas in made to stick (https://www.slideshare.net/JMaystruck/made-to-stick-by-chip-and-dan-heath-how-to-make-your-message-stick) particularly the idea to abstract is much less attractive than concrete. If we can get a “oh I get it, I can install AND configure an application with a single file I can take anywhere” from looking at a single example then that would help boost the uptake of buildout I believe.

We shouldn’t judge a book by its cover but you can see why flask beats pyramid in its popularity by comparing their hello worlds - http://flask.pocoo.org/ vs https://trypyramid.com/ (ignoring the complexity there seem to be 3 official pyramid sites and the first one has no example http://pylonsproject.org).
Given this I would also tend to use something the audience knows like django, flask or pyramid or even simplehttpserver or gunicorn. As long as its short an obvious.

[Jim Fulton]

On Tue, Mar 7, 2017 at 10:16 PM, Dylan Jay <dj...@pretaweb.com> wrote:

> On 7 Mar 2017, at 9:09 pm, Jim Fulton <j...@jimfulton.info> wrote:
>
> > I think it would be nice to have something small that lets the user
> > achieve something useful, e.g. install Django using djangorecipe or
> > something.
>
> The they have a working web server (serving the contents of the buildout directory) halfway through the getting-started section. <shrug>

Sure. It’s silly and its marketing

Sorry. I didn't mean to suggest that it was silly. I have no objection to marketing.  That's no small part of the reason I spent 3 weeks writing documentation. I was just pointing out that the getting started section already has a similar sort of example.

I was partly reacting to django because that would presumably require a database server.

I do think some tools are inherently more abstract than others.  A build tool or a database are more abstract than a UI tool. That doesn't mean we shouldn't try to think of something. I'm all ears.

Jim