Forum: Nitro Nitro/Og cheat sheet styles/ideas/levels....

Hi Devs,
One issues the following examples raise is what is the level the cheat
sheet is aimed at? 'Beginner howto cheat sheet' vs 'Reference cheat
sheet'
Even if there is initially only be one, later there will liley be
more, so it seems worth thinking about nomenclature.
kicking this off with Og since that seems to be the first to be tackled:
Cheat sheets:
 - Og-howto
 - Og-reference

Question:
 Which of these cheat sheets are we starting on?

Existing examples/ideas
Some information packed (reference) cheat sheet examples (for ideas):
http://www.ilovejackdaniels.com/cheat-sheets/ruby-...

Some more 'graphical' ones (beginner/explaining ideas)
http://www.ahoyhere.com/cheats/activerecord_cheatsheet.pdf
http://www.ahoyhere.com/cheats/rails_files_cheatsheet.pdf

I would first ask what is it we want to produce.  In other words:

1) What topics need to be covered
3) A list of use cases and the format that serves each


#1 would require input from George and Tom -- it would leverage their
time really well.   This could start before documentation does.

Reflexively, based on past experience, I see these three formats.  It
should be reexamined with use cases:

1) Tutorial
2) Reference ( Quick vs Complete )
3) Book

My fault as an engineer is prematurely jumping to nuts-and-bolts
"How".    This is a tangent -- but I'd love to see a design for reusable
components that each format can built itself from -- e.g., a Topic
class, with CodeExample, Synopsis, RelatedTopics.

Finally, it makes sense in all of this to see what's been done
elsewhere, and for people like me to spend more time reading through Oxy
and look at other docs we like.

Mark's suggested these, and I think Tom's suggested others (so much
going on here -- time to collate the major points on a wiki ?

http://www.ilovejackdaniels.com/cheat-sheets/ruby-...
http://www.ahoyhere.com/cheats/activerecord_cheatsheet.pdf
http://www.ahoyhere.com/cheats/rails_files_cheatsheet.pdf

Hi folk / Robert

On the small point of our general individual, "...fault as an engineer 
...
[to] prematurely jumping to nuts-and-bolts" (when I am wear my s/w
engineer's hat) -- There are some pedagogical processes that can be
developed for these areas (wearing me adult training cap).

In the specific get me started in a new technically biased (as in lots 
of
technology) topic area, you begin with easily FAMILIAR subject matter 
and
analyse what's called the "training gap".

Software engineers can see this as a user analysis in preparation for
enumerating use cases.

Take a familar - To The User - Scenario and analyse what that person may 
not
possibly know.  Everything, assume nothing.

I believe the most efficient way to accomplish that task is to begin by
developing user profiles of that context and knowledge (assumed 
knowledge)
of each "user class".

That works.

The reason it works is because each role or user class' needs and 
knowledge
is written out and accounted for, they can be tracked.  When a tutorial 
or
training section is ready.  I can actually ask, "Did I get told in 
logical
order?" == Logical order, meaning each topic is presented one idea at a
time, and no new topic/idea is presented before the prerequisites are
presented.

While we may not need such detail, after all everyone knows what a 
database
is for don't they?  (Well actually no.  They might know what the name
means.)  It is like riding a bicycle -- Knowing the word and the 
machine, is
then same as riding it and "knowing it". *grin*

Profile helps others too -- at some point we'll want some marketing.
Profiles are the start of target market segmentation.  It also helps
internals and addon developers understand user requirements and design
paramerters for fixed and on-going change and development (see: 
"Marketing
Myopia", Levitte, 1960, Harvard Business Review).

You will find that different inductions will be needed to begin 
introduction
tutorials different user classes.

Give it a thought.  I believe a user profile main wiki page where people 
can
develop and refind each user class would be a great beginning.

Our general individual "...fault as an engineer ..[to] prematurely 
jumping
to nuts-and-bolts" becomes the advantage of engineering when we jump on 
the
"appropriate" productive "nuts-and-bolts" issues.  Here, I'm suggesting 
user
profiles for the new users are very useful!

cheers,
            Will.



On 04/11/2007, Robert Mela <rob@robmela.com> wrote:
>
> I would first ask what is it we want to produce.  In other words:
>
> 1) What topics need to be covered
> 3) A list of use cases and the format that serves each
>
>
> #1 would require input from George and Tom -- it would leverage their
> time really well.   This could start before documentation does.




My fault as an engineer is prematurely jumping to nuts-and-bolts