Review "1.0/RoughDocs/Getting Started" page

[randomandy]

I felt I could further simplify and streamline the current official  TG Getting Started page. I even broke it into separate pages with that intent.

It is proposed to replace the existing page with this new version.

Please review, comment.

•  Controller: Getting Started
•  Controller: Getting Started Part 2

[Chris Arndt]

• I think the initial paragraph in Part one needs an introductory sentence or two, explaining what this page is about.
• URLs are not file names, so please, instead of ./index, write just /index.
• What ist he purpose of these emtpy URLs?

.. _these urls: 
.. _three urls:

• Please don't use tabs for indentation of example code or HTML.
• Sentences in lists should also have proper punctuation.
• The section title "The Root.default() URL" seems misleading. default is a method, not a URL. Maybe "Implementing a Catch-All URL via the default Method"

[Chris Arndt]

Some remarks on part two:

1) Quote: "In a small application, one module of controllers is all you need. In a larger application, you will likely want to break up your application into separate packages."

Then you go on to show how to split the app into several controller classes not modules. This is confusing. Maybe put the first two paragraphs in the last ("Builing Even Larger") section. Then insert a new introductory paragraph.

2) The page title does not really describe the content of this page properly. Subdividing what? You only handle splitting up into several controllers.

3) "Building Even Larger" - Please use more descriptive section titles.

4) The default method signature has *args and **kwgars but the concept of default arguments and getting arguments through URLs has not been explained yet (applies also to part one). Maybe just leave this out for now?

[randomandy]

• Intro paragraph: I agree.
• URLs not file names: Right. Forgot. I'm new to MVC thinking.
• Empty URLs: They aren't empty. This is an in page link referring to the three localhost links in the subsequent paragraph. I wanted the link to show them in context.
• Tabs: Sorry, vim must have added them. I type in spaces.
• Punctuation styling: ok. done (by Chris)
• "catch all", yes good. Changed.

[randomandy]

Regarding part two:

I don't really have strong opinions about this section. I only removed it from the first page of  Getting Started because it is not needed to get started.

Since I was proposing replacing  the current Getting Started which does include this material, I moved this section to  a new document so it would still exist. I don't think it should even be part of  GettingStartedPart2, but I'm not far enough along in the big picture to have a feeling of where it should go so I welcome anyone else's recommendation.

The only thing I changed was to remove the link to CherrPy and arguments. I feel that the CherryPy docs get too comprehensive too quickly whereas the page  I wanted an argument is very concise and helpful when getting started.

[Chris Arndt]

Part Two: ok, I'll have a look, if I can rephrase part two a bit.

---

I don't know if I like removing links to external documentation. It's an offer to the reader, to delve deeper if he wants to, it's up up to him whether he wants to follow that link.

Removing the link and thereby making it harder to find further documentation looks like treating the reader as immature and not able to think for himself, IMHO.

It's a matter of your general outlook on things, I guess. Do you trust in the intelligence of the users or not?

---

"Empty URLs: They aren't empty. This is an in page link..." Ah, sorry, my bad.

[randomandy]

In retrospect, I suppose it would have been better to have opened a separate ticket for part 2 since it's a different topic and since I didn't write it.... Can these comments be split off into a separate thread / ticket # ?

[randomandy]

As for removing the CherryPy links, I suspect we aren't really so much in disagreement here and in a different place. I am ok with putting those CherryPy links back in, just not in the Getting Started page. I would put them at the bottom of the  Arguments page after the topic has been introduced.

With regard to maturity and intelligence of readers, I think this invites further discussion or explanation on pedagogical philosophy. I'll take that topic over to  GoogleGroups since it isn't specific to only this page.

[Chris Arndt]

Sure, open a separate ticket for part two, if you want, so we can close this one.

[Chris Arndt]

Ok, I promoted the doc to an official doc and placed it under a new URL:

 http://docs.turbogears.org/1.0/GettingStarted/Controller

I replaced the page at the old URL  http://docs.turbogears.org/1.0/GettingStarted/CherryPy with a redirect to the new page.

If you still come up with a better introductory paragraph, please update the Draft page in RoughDocs and I'll update the official page again. Or go through the normal ticket/diff procedure.