this is why developers should never be allowed to write docs for their own software :)

[JCQ]

...cuz newbie rails people like me come across something like this
that sounds great but which assumes too much competence in order to
get around the lack of documentation.

example: followed the 4-step Getting Started dox. Wow, 4 steps, even
an idiot like me should be able to complete it. Nope. Step 4
inconsistent with the reference app. Step 4 states "Setup an admin
controller by attaching it to a model and using the admin layout"
Tried it as literally written, doesn't work. But the reference app
instead does something different: it creates a directory called admin
and then a controller within it named , well, pretty much anything one
wants. often after the resource being admin_assistant'ed. Tried that
too -- no error, well at least I got it to call the admin layout
correctly, though nothing else.

I'm not really complaining, cuz the ability to write clear
documentation isn't a common skill for developers. I'm just flummoxed
that, *knowing that*, we all so often just go ahead and write our own
documentation anyway, thinking that magically we're the one special
person who's the exception to that rule. It's so clear and simple to
us, esp since we're our own experts, so it must be clear and simple
for anyone reading us. Not.

I think it'd be a hell of a lot clearer (if the idea is to get anyone
new to the plugin up and running fast) is to start from scratch
setting up a fresh single controller, single resource Rails app and to
show how admin_assistant is set up for that. As opposed to dropping
the reader into the middle of a reference app containing 3 jillion
feature examples. And don't assume anything -- for all I know my
current not-being-able-to-use-it comes from some silly routing issue
unrelated to admin_assistant but which was assumed to exist.

Yeah, yeah, I know -- no specific error messages, so how can you help
me? I'm not really sure -- in fact were I sure of how you could help
me, I no doubt could also figure out the plugin -- it's just that I've
managed to spend three hours of my life trying to do it the expert
rockstar way and once again finishing another rails evening not having
moved the ball down the field. Big successes are rare; most success
are small and incremental and build up from the simple piece by piece.
I wish documentation would think that way.


p.s. don't worry, the jQuery plugin people are just as bad.

[Francis Hwang]

Heh, well, I wrote the documentation because I'm the only one who's
going to do it. If you know some technical writers who are dying to
write documentation for other people for free, please feel free to
point them my way. :)

As for your specific problem, if you give us more detail I'll be happy
to try to help you out. This is, I think you'll find, a basic
attribute of many open source projects: Many of the expert users are
generally happy to help newbies, but those newbies need to exercise a
lot of patience and detail-orientation to be helpable in the first
place.

Francis Hwang
http://fhwang.net/

[George Anderson]

> Big successes are rare; most success
> are small and incremental and build up from the simple piece by piece.
> I wish documentation would think that way.

JCQ,

admin_assistant is (generously) open source. For that, people are
largely appreciative. If you think the documentation could be
improved, then take the initiative or don't complain. The
documentation lives in the "website" directory in the github repo
(http://github.com/fhwang/admin_assistant). Fork it, fix it, and make
a pull request.

If you need support with figuring out how to fix the documentation,
ask this list. Simply bemoaning the disparity between the
documentation and the plugin helps no one. In fact, it likely serves
only to discourage the author.

/g

--

George Anderson

BenevolentCode, LLC

[Cory Foy]

I admit I was a little baffled too, but I want to make sure I have all
of this right before blogging a tutorial (which you all are welcome to
use).

I also ran through the getting started guide without much luck. What
baffled me was that there was no custom route for the admin namespace
setup in the sample site, which threw me for a loop. So, am I correct
that the complete instructions would be:

1) Do Step 1 and 2 from the guide
2) Create a file called admin.html.erb in app/views/layouts/ and have
it contain:

<html>
<head>
<%= javascript_include_tag("prototype", "effects", "controls") %>
<%= admin_assistant_includes %>
</head>
<body>
<%=yield %>
</body>
</html>

3) Create a directory in app/controllers called admin, and create a
file called blog_posts_controller.rb with the contents from step 4 of
the tutorial

4) Modify config/environment.rb to have "include admin_assistant" as
the last line

5) Modify config/routes.rb to have:

map.namespace :admin do |admin|
admin.resources :blog_posts
end

6) Restart your webrick server if it was already running

7) Visit http://app/admin/blog_posts

8) Profit!!! (Sorry)

Again, what I find interesting is that the reference app doesn't have
the admin route set, but does include admin_assistant in
environment.rb. Am I doing more things than I should, or does this
seem to be right?

--
Cory Foy
http://www.coryfoy.com
http://twitter.com/cory_foy

[Francis Hwang]

Yeah, it's tricky. I guess I wrote the "Getting Started" page to not
be for total noobs but for people who had a moderate amount of
familiarity with Ruby & Rails. I'm not really opposed to the idea of a
tutorial for absolute beginners too, but it's probably worth having
one for each because a lot of AA users are going to be people with
significant Rails experience.

A few points, just to make sure I've got it right too:

On Nov 18, 2009, at 1:42 PM, Cory Foy wrote:

> 4) Modify config/environment.rb to have "include admin_assistant" as
> the last line

Cory, how are you including admin_assistant in your Rails code? If you
do ./script/plugin install git://github.com/fhwang/
admin_assistant.git, you shouldn't need to modify environment.rb at
all. I'm realizing now that the reference app does "require
'admin_assistant'" in config/environment.rb; that appears to have been
the consequence of trying to use it as a gem but I don't think that's
necessary either.

> 5) Modify config/routes.rb to have:
>
> map.namespace :admin do |admin|
> admin.resources :blog_posts
> end

I'm not so great with routing, but I don't think this is necessary
either, right? The reference app doesn't have any route like this.

Anyway, thanks for the specific input -- I'll try to absorb this into
the documentation somehow.

Francis Hwang
http://fhwang.net/

[Francis Hwang]

Hey Cory, I've renamed the "Getting Started" to "Quick Start", and
added a "Tutorial" as well. So now there are points of entry for
exprienced Rails devs and for n00bs. Check it out, and please let me
know if you see any issues with it.

Thanks,

Francis Hwang
http://fhwang.net/

On Nov 18, 2009, at 1:42 PM, Cory Foy wrote:

> --
>
> You received this message because you are subscribed to the Google
> Groups "admin_assistant" group.
> To post to this group, send email to admin_a...@googlegroups.com.
> To unsubscribe from this group, send email to admin_assista...@googlegroups.com
> .
> For more options, visit this group at http://groups.google.com/group/admin_assistant?hl=
> .
>
>