Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Updates to Working-With-Data #42

Closed
wants to merge 2 commits into
from

Conversation

Projects
None yet
4 participants
Contributor

AndrewPodner commented Jan 4, 2013

Restructures the pages into logically grouped subjects.
Adds In-page anchor based navigation to longer pages.
Creates a page (working-with-records) that covers query config, CRUD, finder...
Expands the model creation and configuration page.
Breaks out the Data Concepts into a short overview page

NOTE: This uses an approach of longer pages covering a larger subject matter. Alternately, there may be a benefit to an approach with short pages covering single, or a few closely related methods to put more specific topics into the left menu, which may improve user experience and speed up the user's ability to find what they are looking for. Just a thought.

NOTE: The blockquote tag would be handy in this manual for tips, tricks, shortcuts, and caution/warning statements. Currently, the li3_docs CSS font size for blockquotes in the markdown class is about 2em, which renders it unusable. Would like to either change it in li3_docs or override it if possible.

-Andy

AndrewPodner added some commits Jan 4, 2013

@AndrewPodner AndrewPodner Revision of the `working-with-data` folder that:
Restructures the pages into logically grouped subjects.
Adds In-page anchor based navigation to longer pages.
Creates a page (working-with-records) that covers query config, CRUD, finder...
Expands the model creation and configuration page.
Breaks out the Data Concepts into a short overview page
952034d
@AndrewPodner AndrewPodner Update menu to fix broken link to li3_qa file. bd56c17

@nateabele nateabele commented on the diff Jan 4, 2013

en/working-with-data/working-with-records.wiki
@@ -0,0 +1,344 @@
+<a id="top"></a>
+
+# Working with Records
@nateabele

nateabele Jan 4, 2013

Owner

The problem with this title is that 'records' implies relational data, whereas these topics apply equally to relational and document-oriented databases.

@gwoo

gwoo Jan 4, 2013

Owner

We use Entity as the most abstract. maybe working-with-data/using-an-entity?

@AndrewPodner

AndrewPodner Jan 4, 2013

Contributor

Thats a good point, I struggled with that title. Actually I struggled with creating a single page that large & broad. find() and finder() could nearly stand on their own. I was really trying to keep the perspective of a less advanced user as I go through this and think of terminology that would be intuitive to such a person. It's a fine line to walk.

@AndrewPodner

AndrewPodner Jan 4, 2013

Contributor

I agree entity is technically broad and abstract enough, but someone picking it up for the first time may not catch that based on the menu title.

I look at it from the perspective of trying to quickly answer questions like:

  • How do I get records from the database?
  • How do I do validation?
  • Where do I put models & what if the Model name and table name don't match?

So I guess the question in my mind as I am going through it is, "Does what I am doing allow those questions to get answered, irrespective of the user's familiarity with the framework"

@gwoo

gwoo Jan 4, 2013

Owner

Yeah, I think that's why it was called "using models". They are the answer to those questions.

@AndrewPodner

AndrewPodner Jan 4, 2013

Contributor

When I hear model, I think of a class that I am going to create in the models directory.

If the overall consensus is to keep the terminology abstract and equally applicable, I can certainly do that; maybe another part of the answer would be to expand the quickstart section and put some How Do I? type "translations" in there that will take very familiar terminology and link it into these pages. There can't be more than 10 or 15 tasks like this that could be used as a jump off point to get people to make a mental association with concepts like SQL Row/Record = Lithium Entity.

Just a thought.

@gwoo

gwoo Jan 4, 2013

Owner

Oh I like that. Maybe we have a "Start here" section that provides a bunch of definitions and terminology.?

@AndrewPodner

AndrewPodner Jan 4, 2013

Contributor

Yeah, I mean basically a person is potentially one of 3 archetypes using Lithium in my view:

  • A core developer of Lithium (not someone you need to worry about teaching, lol)
  • A convert from another framework (my gut says this is ~70-80% of your potential users)
  • Someone picking up a framework for the first time (the remainder), and there just doesn't seem to be that big of a pool of advanced programmers flipping from procedural to OOP at this point. To me this means newer people.

The next natural question that will follow is, "from where will the converts come?" My guess would be any non-5.3 framework, especially if there is not a clear 5.3 version actively under development and reasonably close to release.

I don't know, this is a lot of my typical marketing pontification that leaks out from time to time. I am just trying to get clear in my mind what the right answer looks like to get someone from download to successful app with as little frustration as possible and get them to a point where when they are stuck, the first thought is, "oh let me go look that up in the user guide".

I hate using terms like "dumb down" becuase that really doesn't say it right, but I do think it has to be simple enough not only for less advanced coders, but also for people whose first language is not English.

$andy->end('random_babbling')

Owner

nateabele commented Jan 4, 2013

Good call on the chapter anchors. The structure looks good overall, but I'll review in-depth as I have time. I doubt li3_docs is currently using <blockquote />s, so feel free to patch away. /cc @raisinbread

Contributor

AndrewPodner commented Jan 8, 2013

Closing so I can restage in a branched local repo. Will resubmit.

@AndrewPodner AndrewPodner added a commit to AndrewPodner/manual that referenced this pull request Jan 8, 2013

@AndrewPodner AndrewPodner #42 re-commit to clean up local repo 2b8292c

@AndrewPodner AndrewPodner added a commit to AndrewPodner/manual that referenced this pull request Jan 9, 2013

@AndrewPodner AndrewPodner #42 add the `delete()` method, refactor records to entities, and make…
… adjustments to sample code in data-concepts
a6ec7b3
Owner

raisinbread commented Jan 9, 2013

Andrew, one thing I've been working (but has been neglected as of late) is a restructure of the manual (found in the branch of the same name). Would you mind taking a look at that as well? I think you've got some great feedback and work here: I'd just like to make sure it gets incorporated with the latest work.

Contributor

AndrewPodner commented Jan 9, 2013

Most definitely. would you prefer that I work and commit to that branch instead?

Another thing I would like to do is get a README.md file into each directory in the manual so that each section has a home page maybe with some overview information and another set of navigation, just to be sure that nobody clicks a menu item and comes up with a blank page.

Owner

raisinbread commented Jan 9, 2013

Yes.

And yes, though I'm not a huge fan of content for the sake of content. If we can find a way to make those interstitial pages useful (or maybe entertaining?), that'd be best.

I'd like to move to this new branch ASAP, so maybe us two can take it this last mile together. Thanks for your help, Andrew.

Contributor

AndrewPodner commented Jan 9, 2013

Glad to be involved. Appreciate the kind words.

to keep confusion to a minimum on this PR, maybe we can finish tidying it up, and when it is ready for merge, I will close this PR and reopen it in the other branch

@AndrewPodner AndrewPodner added a commit to AndrewPodner/manual that referenced this pull request Jan 9, 2013

@AndrewPodner AndrewPodner #42 refine the verbage around dynamic finders and the additional find…
… menthods like `first` and `all`
6801305
Contributor

AndrewPodner commented Jan 9, 2013

@raisinbread Just looking through the restructure branch. This is really well organized. Please let me know what sections you feel like need some more work. Happy to help as it looks like this will be a big step forward for the guide.

@AndrewPodner AndrewPodner added a commit to AndrewPodner/manual that referenced this pull request Jan 9, 2013

@AndrewPodner AndrewPodner #42 clean-up whitespace 695f1c2
Contributor

AndrewPodner commented Jan 12, 2013

seems like this one has quieted down to a point where I can move the PR to the restructure branch, so any final tweaking can be managed there.

Owner

raisinbread commented Jan 12, 2013

If you're looking for ways to help there, I'd just pick a section that's empty and fill it out. That's probably the most immediate need. I'm working on the Environment guide now.

Just let me know which one you're working on so I don't step on your toes.

Contributor

AndrewPodner commented Jan 13, 2013

There is a todo for a MySQL tutorial, I will start there. Any place it should go, or are you planning on a new folder for tutorials?

On Jan 12, 2013, at 1:59 PM, John Anderson notifications@github.com wrote:

If you're looking for ways to help there, I'd just pick a section that's empty and fill it out. That's probably the most immediate need. I'm working on the Environment guide now.

Just let me know which one you're working on so I don't step on your toes.


Reply to this email directly or view it on GitHub.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment