Kill Hello World section on home page

[stevepiercy]

The Hello World example on the home page emphasizes "quick" and "easy to start" before any other selling point. No one develops web apps in Pyramid in the manner shown in the Hello World example. It's Flask-y. Let's kill this section.

• Add two more representative code examples to PR Replace Hello World with usage examples on home page (src/templates/i… #47 .
• @blaflamme tweak the design and layout

[blaflamme]

I'm ok with this idea but providing somehow a code example of how it looks and feels could be relevant, let see what can be done.

[stevepiercy]

How do you represent Pyramid's look and feel in a code example? I don't think it can be done concisely on a marketing site because, in practice, it spans many files, which would occupy a lot of design real estate.

Thinking out loud, maybe a simple how to configure a route to a view, with some explanatory narrative text? Meh, then that's misleading as "simple" or "the way to do things".

What's a common usage pattern that is Pyramid-y?

[cguardia]

When writing my web framework report, I ran into this issue when I wrote small 4-5 page outlines for some frameworks. How to communicate in a short space what it feels like to work with a framework? I ended up showing three snippets of "representative" code for each framework. For Pyramid, I chose view predicates, renderers, and asset specifications. I didn't use full fledged examples, just a few lines to illustrate each feature.

Not saying this idea is useful for this situation, just adding some food for thought.

[stevepiercy]

Something like this?

My narrative might look good in the first example, but it is probably gibberish to the pedantic.

[pauleveritt]

Steve, just the kind of thing I was thinking of. I was going to put it in an animated image, but I think yours might be better.

—Paul

On Dec 20, 2015, at 5:17 AM, Steve Piercy [email protected] wrote:

Something like this?

https://cloud.githubusercontent.com/assets/102112/11917517/195da9c4-a6bf-11e5-8e79-4e1dd2306276.png
My narrative might look good in the first example, but it is probably gibberish to the pedantic.

—
Reply to this email directly or view it on GitHub #31 (comment).

[blaflamme]

Yes I think we need to expose some patterns/idioms, here and there, if we're too abstract people will need to dig too far before they get some taste. I don't think we need full context, and yes we'll have to make choices even if we can do other ways (that's a problem we have to live with). We already do choices by using SQLA and Jinja to show people things they already know or have a taste of and then it's easier for them to have a point of comparison.

We can also have a kind of more complex hello world example that exposes more basic concepts and have a way to simply explains things like the config object, predicates, renderer and assets.

@cguardia Do you have some reference material you did you can share?
@pauleveritt Do you have some material from your video sessions or pycon workshop we can pick from?

[stevepiercy]

I created a new branch https://github.com/Pylons/tpc/tree/usage-pattern-examples in favor of PR #33. The new branch can also replace #32.

Please add common usage patterns to the template @cguardia @pauleveritt.

[pauleveritt]

Well, now that I’ve agreed with Steve, I also agree with Blaise. :) On one hand, we need to focus on differentiating. OTOH, the first touch needs to be accessible.

I don’t yet have a way to square that circle. Perhaps something like a carousel, which shows a progression in a space-economical way.

Between O’Reilly and other material, I have lots of sources that “start small, finish big”. But I need to think of it in terms of how it is portrayed on the page.

—Paul

On Dec 20, 2015, at 1:56 PM, Blaise Laflamme [email protected] wrote:

Yes I think we need to expose some patterns/idioms, here and there, if we're too abstract people will need to dig too far before they get some taste. I don't think we need full context, and yes we'll have to make choices even if we can do other ways (that's a problem we have to live with). We already do choices by using SQLA and Jinja to show people things they already know or have a taste of and then it's easier for them to have a point of comparison.

We can also have a kind of more complex hello world example that exposes more basic concepts and have a way to simply explains things like the config object, predicates, renderer and assets.

@cguardia https://github.com/cguardia Do you have some reference material you did you can share?
@pauleveritt https://github.com/pauleveritt Do you have some material from your video sessions or pycon workshop we can pick from?

—
Reply to this email directly or view it on GitHub #31 (comment).

[stevepiercy]

As far as presentation of information: http://shouldiuseacarousel.com/ 😬

Let's get the other two examples in first, giving @blaflamme some Legos to play with for the design.

Hello World app may be OK on a secondary page, but I think on the home page would be sending the wrong emphasis. On a secondary page we can elaborate that yes, you can build a simple single-page app, but in practicality you probably never will.

[goodwillcoding]

I would not kill hello world. In fact I think we do need some kind of "hello world" plus a call out to "Go here to learn more" potentially leading to a tutorial.

[stevepiercy]

There are two "hello world" in the official docs already. That's another reason for killing it off here. Duplication of docs is bad.

• http://docs.pylonsproject.org/projects/pyramid/en/latest/
• http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/firstapp.html#hello-world

[goodwillcoding]

@stevepiercy ... its been super painful navigating people to that. Saying go to "trypyramid.com and start there easily" is what I am looking for

[stevepiercy]

When trypyramid.com gets deployed (see open issues and PR #30 where most of these changes have already been completed), then you can tell people to go to trypyramid.com, click "Resources", and pick the right tutorial for their interest, skill level, and experience.

trypyramid.com's purpose is to make it easy to find the right resource to start using Pyramid.

"Easy" is subjective: newbs to Python or web frameworks will not find Pyramid easy.

It is terribly misleading to imply that the ease of creating a "Hello World" web app equates to a practical web app. Let's align expectations with reality and not preach impractical habits from the start.

[goodwillcoding]

When I said "easily" I meant it is easy to find information ... I guess a comma was missing.
I do not assume the audience is just newbies. The might just be people new to pyramid. One of the audiences for try pyramid is Developer. I would argue for a no-click engagement, there is nothing impractical about that :)

[stevepiercy]

Did you build PR #30? How would we turn away developers with the changes that are both proposed in the open issues and in PR #30?

What would a developer learn by following a Hello World example? They would learn bad organization, bad project structure, and a false sense of what Pyramid can really do for them.

We're helping developers by not misleading them into thinking Pyramid apps follow the "Hello World" example. That's an improvement.

[pauleveritt]

Hmm, sounds like having them learn on the cover of the book (trypyramid) and go into the book (the docs) for the introduction.

I guess we need some more thinking on what is the purpose of having a code snippet on the tippy-top of the entry point into the world of Pyramid. trypyramid.com is a marketing site, not a learning site. It is aimed at people exploring different frameworks.

“What would a developer learn” isn’t the right question. They haven’t made a commitment yet to learning. They need to be persuaded that it’s worth the time to try learning.

“hello world” is a way to calm the fears of novice developers. It’s ok to say they are not the audience for the marketing site, nor Pyramid. But let’s be very intentional about that. In the tutorials I’ve done, I always start with the simplest possible step. After 10 steps, I start showing stuff that makes Pyramid unique. By then, they can handle a little abstraction and complexity.

—Paul

On Jan 2, 2016, at 6:11 AM, Steve Piercy [email protected] wrote:

Did you build PR #30 #30? How would we turn away developers with the changes that are both proposed in the open issues and in PR #30 #30?

What would a developer learn by following a Hello World example? They would learn bad organization, bad project structure, and a false sense of what Pyramid can really do for them.

We're helping developers by not misleading them into thinking Pyramid apps follow the "Hello World" example. That's an improvement.

—
Reply to this email directly or view it on GitHub #31 (comment).

[goodwillcoding]

I mostly agree with @pauleveritt, or at least I think I do. TPC does not have to have to be a full learning site, just the entry point.

However I disagree that developers new to pyramid are not an audience for the site. I guess the question is the stated purpose of what the site is supposed to cover and which audience it addresses. I think it is possible that it can have sections for varied ones.

This list is just a try so feel free to expand but I am guessing we want marketing for:

Developers

• newbies
• not newbies

Business Case Makers for use of Pyramid over other frameworks

• technical
• non-technical

Community members who want to be involved

• new ones
• old one

@stevepiercy If hello world example is something that you think will take people on the wrong path, we can update the follow to it of something "now learn how to do it right"

[blaflamme]

I think it's important to have some snippets that shows how the code looks like. We can just have a small decorated view to get a feel... like when I went to the haskell website you get a feel of the syntax, https://www.haskell.org

Ir could be as simple as

@view_config(route_name='home')
def home(request):
    return Response('Welcome!')

You don't need to show a full example and explain, just show how concise and expressive it is.

[stevepiercy]

When I started learning Pyramid, the collection of too many sites of "how to do Pyramid" was (and still is) too confusing (www.pylonsproject.org, docs.pylonsproject.org, Pyramid Tutorials, Pyramid Cookbook, and the official narrative docs for Pyramid). It is harmful to repurpose trypyramid.com into yet another "how to do Pyramid".

trypyramid.com's purpose is to provide an entry point to all the Pyramid sites, and persuade all the audiences to dive in. That will be a tremendous improvement for the new-to-Pyramid audience. And the new www.pylonsproject.org will help a lot, too. A Hello World on trypyramid.com would get in the way, and it would turn off developers who think, "no one builds practical projects like this".

@goodwillcoding to see the replacement of Hello World as a visual representation, please see the screenshot above, or more precisely the actual code in PR #33 which is also referenced above.

Also @goodwillcoding if you haven't built the app from the merges and the pending PR #30, I strongly recommend you do that now. Then you can see what is the culmination of everyone's contributions over the last couple of years.

@blaflamme we need two more code examples, one for renderers and another for asset specifications, per the discussion above.

[goodwillcoding]

@stevepiercy I checked out the "page-media" of your fork and built it. It still has the Hello world example in it right? So I am not sure what you mean.

There are tons of project site which feature a hello world. It is a very common and proven approach. Most dev's have been trained to expect it. The hello world does not need to be that code snippet I am open to suggestion, but I strongly feel that it provides a fair entry point. It still needs "What do I do next" call to action below of like "Build a small app".

[blaflamme]

I don't think showing an hello world simple app is endorsing a way to create complex app, and any patterns we'll propose won't reflect more than our own way of doing things. Pyramid is flexible and we have to deal with that.

But again, showing snippets help people having a quick idea of what's going on and they dont need the full context, tutorials are there for this task.

[stevepiercy]

@goodwillcoding there's a separate branch, usage-pattern-examples for the changes.

@blaflamme I just now pushed in your code sample above to that branch.

[stevepiercy]

I've killed off the outdated branch usage-pattern-examples in favor of PR #47.

This should make it easier for folks to add any code samples, or just paste them in this issue and I'll do the committing and pushing to that PR.

[stevepiercy]

I've pushed the missing code examples and narrative to PR #47. Feedback sought. I want to resolve this issue and avoid stagnation. @blaflamme @cguardia @goodwillcoding @pauleveritt @mmerickel @bbangert

[stevepiercy]

Closed by #47

[sontek]

I just stumbled on this ticket because I was trying to help someone get started with Pyramid and sent them to trypyramid.com and then they couldn't get started because there is now nothing on trypyramid.com to help people build their first pyramid app.

I disagree with the fact that we want the most complicated parts of Pyramid upfront and center for people trying to evaluate a new webframework. Pyramid is SIMPLE and POWERFUL. We should show people the simple side of Pyramid and allow them to grow into the powerful parts.

1. I'm not sure why Function Decorators is a thing we need to tout as a main selling point?
2. Predicates and Events are advanced features that aren't required to build your APIs in Pyramid
3. Renderers/Asset Specs don't really shine as features if you don't know what they are or why they are good and this update doesn't do a good job of describing them.

I would like to see us go back to the single page app demo that helps people get started and tout the simplicity of Pyramid upfront. This is an era of microservices where people are looking for a quick way to build an API.

[cguardia]

Why not re-add the quick start app at the top, then keep the examples as they are?

[blaflamme]

I would propose same than @cguardia :)

[mmerickel]

For my 2 cents I agree with @sontek that a full working code snippet such as the one we have in the pyramid docs is important to have as the first thing. After that perhaps you can add more advanced things but many people are very simply looking for a request-response example.

from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from pyramid.response import Response

def hello_world(request):
    return Response('Hello %(name)s!' % request.matchdict)

if __name__ == '__main__':
    config = Configurator()
    config.add_route('hello', '/hello/{name}')
    config.add_view(hello_world, route_name='hello')
    app = config.make_wsgi_app()
    server = make_server('0.0.0.0', 8080, app)
    server.serve_forever()

[stevepiercy]

There were many IRC discussions about why removing the "hello world" was a good idea, the points for which are summarized above. For those reasons "Hello World" front and center is a very bad thing.

trypyramid.com is for persuading people why they should try Pyramid. It is not for showing people how to get started with Pyramid other than providing entry points under Resources.

[cguardia]

But it should still be easy to get to the how to start right away, without having to find the links under the cryptic "resources". How about at least some text and a link?

"If you are looking to get started with Pyramid, we have a great quick tutorial".

That, or a get started button with more visibility than resources.

[sontek]

trypyramid.com is for persuading people why they should try Pyramid

Isn't how simple it is one of the reasons people should try Pyramid? I disagree that Function decorators, events, and asset specs are core reasons for using Pyramid.

[mmerickel]

I have to agree that it seems ironic our tagline is "start small, finish big" yet the first code examples are things that are entirely optional (the finish big part). I'd really like to have the hello world front and center myself, otherwise where's the start small part at?

[cguardia]

I think that given the sad state of our other entry points (Pylons confusion, ugly urls, out of date designs and colors, etc.), this is the one site that we can point at with some pride (thanks @stevepiercy and @blaflamme). That means we have to keep the "how do I use this" people in mind and not just whatever the original intended audience might be.

[cguardia]

We can even use the tagline to our advantage. Feature the hello world under a Start small... heading, then the other examples below Finish Big.

[cguardia]

#101

[stevepiercy]

trypyramid.com has multiple target audiences, including CTOs, CFOs, and other non-developer decision-making folks. Emphasizing "hello world" front and center for that audience is not helpful. There is some content missing from the home page for that audience, but I don't know what that is or how to represent it. I am not a CFO.

I'm not opposed to restoring "hello world", but I don't know the right way to do it.

IMO, restoration of "hello world" should include a disclaimer with links to relevant bits, something like this:

Even though this one-file app example demonstrates how quick and easy it is to create a simple request/response web application, it is not scalable. Experienced developers write web applications by reading APIs and documentation, and as demonstrated in the tutorials and community cookbook recipes. Pyramid has a rich pool of resources from which to draw, and can be easily extended.

[goodwillcoding]

So as bigger topic, I do not think there is any way to make 1 page target so many multiple audiences though. We probably need a page that says "for non-developers" or "hey-cfo-here-is-why-you-want-pyramid" and have a button on the home page that says something "Need to learn business value of Pyramid, see here".

Personally I think a hello world example has been proven to appeal on a marketing level, thought of course it is the lowest common denominator. But it is simple and can be the starting point from which we can take the user to the a more complex example.

[cguardia]

@stevepiercy is there some site for other frameworks/tools where you think CxO audience is well represented?

[sontek]

For me personally, I've handed trypyramid.com out so many times to get people started and today was the first time someone came back and was like "Why did you send me here?". That hello world example has helped me so much when showing people how to get started with Pyramid.

As we sit right now I feel like I don't have a good entry point to send people now that it is gone. Even if its not on the front-page I'd love for it to come back so I still have a place to send people.

[goodwillcoding]

I think we should definately include something for C*Os ... but the hello world need to come back IMHO

[cguardia]

Any thoughts on my suggestion on #101 to keep both quick start and examples?

[blaflamme]

I would bring back the hello world and get rid of the other snippets block until we come up with a better solution. I don't want to loose referenced people that get «started up», since we already know it's been used for this purpose for some time. For other targets it's speculation for now, until we really take action to bring them over there.

[cguardia]

I don't agree there, because we had some consensus that the examples were a good idea and work has been done on that front. We are not losing referenced people, since hello world will still be there at the top with relevant links. I believe what is speculation is how to attract CxO's, which I agree has not been done.

[goodwillcoding]

I vote for hello world.

Nott sure what "loose referenced people" is.

[cguardia]

@goodwillcoding it doesn't need to be one or the other. You are saying you just want hello world and prefer no examples below that?

[blaflamme]

«referenced» people means people coming or sent out there to get started using pyramid as pointed out by sontek.

@cguardia why I would replace, because the consensus was to replace hello world by snippets, and then we bring it back while keeping snippets. I proposed the idea of having snippets when it was decided to remove hello because I think it's important to get a feel of what pyramid looks like when you reach that page. I think if we keep both in a row the way it's done now is more confusing than helping. That's why I propose to get rid of the snippets till we find the right way of expressing it.

[goodwillcoding]

if by example you mean what is currently up there the examples are fine, though I wonder if they take up too much space and should go to their own page

[cguardia]

@blaflamme fwiw, if it's clearly separated, like in my PR, I don't see why it could be confusing. On the other hand, I can understand space concerns like @goodwillcoding mentions. For myself, I like the examples in there.

[goodwillcoding]

Anyhow I say we pull in #101 and publish it

[stevepiercy]

After reviewing the PR #101 from @cguardia here are my thoughts.

1. There is no information about how to install Pyramid; it's a code sample with narrative text alongside. This is a change from the original where instructions for installing Pyramid were provided. I favor this change because it will force users to figure out how to install Pyramid for their system by looking in the official docs, which is where they should be directed to learn how to do something. I also want to avoid duplicating docs at all costs, and this achieves that objective.
2. Per the previous point, a link labeled how to install Pyramid is needed in the narrative text.
3. I like the incorporation of the tagline to illustrate "start small" and "finish big". That works for me.
4. The narrative text needs minor wordsmithing. I can work on that after merging. I also want to make it clear that "hello world" is a minimal example of a request/response app in Pyramid, and does not demonstrate the actual ease of creating web applications of any size with Pyramid.

I created a new issue #102 to address the separate matter of C*Os as a target audience.

[cguardia]

@stevepiercy added link to install docs.

[cguardia]

@stevepiercy anything else you think is missing for this to be merged? Thanks.

[blaflamme]

@cguardia almost good, I'll rework a bit your heading title.

@stevepiercy I dont think anyone would think the hello example is the way to create an app in pyramid. Flask, bottle, web.py, and others expose the same little app and there's no confusion.

[blaflamme]

merged and deployed, add pull request for more fixes or proposals.