Task #27567

Task #27561: Complete documentation

Reorder chapters

Added by Karsten Dambekalns over 10 years ago. Updated about 10 years ago.

Status:
Resolved
Priority:
Should have
Assignee:
-
Category:
- Documentation -
Start date:
2011-06-20
Due date:
% Done:

100%

Estimated time:
Sprint:
PHP Version:
Has patch:
Complexity:

Description

The chapters are not ordered in the way we explain(ed) parts of FLOW3 in sessions/workshops/tutorials so far, maybe we should do that...

#1

Updated by Karsten Dambekalns over 10 years ago

  • Status changed from New to Needs Feedback
#2

Updated by Sebastian Kurfuerst over 10 years ago

I'd suggest the following structure of the chapters:

  • Introduction
    • General Principles (NEW) -> should contain something about "Convention over Configuration"
  • Installation
  • Packages -> rename to "Package Management"
  • Configuration Framework -> rename to "Configuration"
  • Object Framework -> maybe rename to "Object lifecycle and Dependency Injection" (as DI will be the buzzword most people will look for)
  • Persistence Framework -> rename to "The Persistence Layer"
  • MVC Framework -> rename to "Model View Controller Framework"
    • Introduction
    • Request and Response
    • Controller
    • View
    • Routing
  • The command line (NEW)
  • Resource Management

I am not yet so sure about the following ones, where to place them:

  • Caching framework
  • Error/Exception handling
  • Signal/Slot
  • Security Framework
  • Aspect-Oriented Programming
  • Property Mapping Framework

I would remove the following ones:

  • FLOW3 Bootstrap -> I would remove this chapter completly, and move the contents to "Configuration"
#3

Updated by Karsten Dambekalns over 10 years ago

Sebastian Kurfuerst wrote:

I'd suggest the following structure of the chapters:

Fine with me, the omnipresent use of "framework" was something already removed on the file level, fine with me to get rid of it more.

  • Introduction
    • General Principles (NEW) -> should contain something about "Convention over Configuration"
  • Installation
  • Packages -> rename to "Package Management"
  • Configuration Framework -> rename to "Configuration"

Hm. Is this about configuring FLOW3 or about the configuration mechanisms in place? "Configuration" sounds like, "oh, I'll check here to see how DB credentials need to be set" - but that would be wrong. Maybe "Configuration Handling"?

  • Object Framework -> maybe rename to "Object lifecycle and Dependency Injection" (as DI will be the buzzword most people will look for)
  • Persistence Framework -> rename to "The Persistence Layer"
  • MVC Framework -> rename to "Model View Controller Framework"
    • Introduction
    • Request and Response
    • Controller
    • View
    • Routing
  • The command line (NEW)

Of course some introduction to CLI needs to be given way earlier, in installation probably.

  • Resource Management

There should be some very basic intro to Fluid somewhere (MVC -> View), I'd say.

I am not yet so sure about the following ones, where to place them:

I'd add them after resource management, in the following order:

  • Property Mapping Framework
  • Aspect-Oriented Programming
  • Security Framework
  • Signal/Slot
  • Caching framework
  • Error/Exception handling

Reason for putting AOP before Security and Signal/Slot: the latter two use AOP. Of course we can also bump security up ilk this:

  • Property Mapping Framework
  • Security Framework
  • Signal/Slot
  • Aspect-Oriented Programming
  • Caching framework
  • Error/Exception handling

I would remove the following ones:

  • FLOW3 Bootstrap -> I would remove this chapter completly, and move the contents to "Configuration"

I'd rather keep it, maybe rename it, yes. But "Configuration" is the wrong place, it's not about configuration (only), is it? Maybe make it an appendix, or create an "Inside FLOW3" chapter where some details, ideas and decisions are explained that fit nowhere else.

#4

Updated by Karsten Dambekalns over 10 years ago

Karsten Dambekalns wrote:

I'd add them after resource management, in the following order:

  • Property Mapping Framework

Thinking about it another second, isn't this somehow part of MVC, from a users perspective? No, but there is overlap, so careful here...

#5

Updated by Sebastian Kurfuerst over 10 years ago

  • Configuration Framework -> rename to "Configuration"

Hm. Is this about configuring FLOW3 or about the configuration mechanisms in place? "Configuration" sounds like, "oh, I'll check here to see how DB credentials need to be set" - but that would be wrong. Maybe "Configuration Handling"?

Hmm, I'd expect somehow both in this chapter: Explaining the concepts, and also explaining the key configuration directives. No?

Of course some introduction to CLI needs to be given way earlier, in installation probably.

Yeah, this is more the in-depth explanation I think. Btw: Maybe the first chapter should be a "quickstart tutorial"? Grails does it this way, and I like it quite a lot; as it removes fragmentation, and is easier to maintain.

There should be some very basic intro to Fluid somewhere (MVC -> View), I'd say.

Yep!

I'd rather keep it, maybe rename it, yes. But "Configuration" is the wrong place, it's not about configuration (only), is it? Maybe make it an appendix, or create an "Inside FLOW3" chapter where some details, ideas and decisions are explained that fit nowhere else.

OK, or we can do "The bootstrap process in detail" as one of the last chapters.

  • Property Mapping Framework

Thinking about it another second, isn't this somehow part of MVC, from a users perspective? No, but there is overlap, so careful here...

Well, yeah, I think we should explain in the MVC framework how it is used, but then link to the in-depth chapter for further details.

Greets,
Sebastian

#6

Updated by Sebastian Kurfuerst about 10 years ago

  • Status changed from Needs Feedback to Resolved
#7

Updated by Karsten Dambekalns about 10 years ago

  • % Done changed from 0 to 100
#8

Updated by Karsten Dambekalns about 10 years ago

  • Target version changed from 1230 to 1.0.0

Also available in: Atom PDF