Mohit S. wrote:
Chris P. wrote:
For one, I have actually seen, read and followed the documentation on
the Radiant CMS website.
Fine. But would you not admit it could be improved? An example: page 1
might mention for instance:
- What servers the app will/ will not run on.
- What databases, ditto
Isn’t this important for a CMS? I don’t think info like this is
presented logically enough by most document sets, and that’s basically
what I’m whingeing about here.
Let’s not forget that a web-enabled CMS running on Rails (or .net or
J2EE or PHP, etc.) is not an end-user tool. It is not a download and
run like, say, a media player. It’s meant for a technical audience to
set up and pass to their clients - the clients should see what they see
when they log in. So, while I can try to see what you are saying, the
issues are slightly different when talking engineer-to-engineer and
engineer-to-client.
Fair enough, I take your point. However, I would argue on this, 2
points:
- I believe a CMS has two classes of user, and the owner and his staff
have a right to be called the end user. The other party, the visitor, is
a non-involved form of user who does not fully qualify for the term
end-user since they might only be present for 8 seconds once in their
lifetime. The true end-user, the CMS tech staff, work with it every day.
Another term is needed for visitors, but I don’t think end-user is
appropriate.
- Of course you are right when you point out the difference. But I
believe that OSS usually makes the fundamental error that engineers need
very little help, and if they ask for it they must be deficient. I
cannot agree here. Take the case of a radio engineer opening up a
transmitter to repair it - he needs all the help he can get. The
‘end-user’ might possibly be interpreted as the remote listener (and
this parallels the previous item) - but which of the two needs the tech
assistance? The listener or the engineer?
So, starting from the beginning - an application user manual needs to
start correctly. This is done by stating who the document is for, then
linking to other locations in the same space, for docs for other types
of users.
Same point as above.
surprises later when you find it won’t install on your Sun Solaris/
It can be installed:
before you even start do anything or touch anything, everything possible
should be defined - so there are no questions whatsoever.
I agree (up to a point) and there’s a plan with regards to Radiant in
that direction.
http://lists.radiantcms.org/pipermail/radiant-docs/2007-December/000034.html
This is interesting. I see that you are doing what you can. So there is
perhaps a little room for improvement? Delete that last bit - of course
there is, even with mature projects. I should not criticise more, as you
are clearly trying to sort it out.
Best not carry on I think, enough’s enough. If you seriously think I
could help further, I would be very glad to help - honestly. You need
two people to write a manual - one who knows the equipment, and one who
can get that knowledge on paper in a way that others can comprehend. OSS
projects don’t seem to appreciate this; the one way that never works
(and never has, in any field of engineering) is to get the technicians
themselves to author it.
Well, it can’t be helped. For some reason (and this is a sweeping
generalization), perhaps enough professional document writers are not
getting involved with open source projects. I’m sure if you got in
touch with any OSS project and told them that you are a professional
technical writer and would like to write documents for them, they’d
welcome you with open arms and a beer.
I thoroughly believe you are right, there aren’t enough tech authors
assisting. I did try to help a project once, but they turned it down,
and I got the feeling it was kind of a clique - if you weren’t in, they
didn’t want to know. No problem for me, I have enough to do.
But, on the other hand, it’s silly to say - OSS projects are doomed
because they can’t write documents. They are doing more than enough
writing the code so that the option exists. It’s nice of them to even
write some documents… ideally someone else should play that role.
I guess you’re right, the application is the important thing. Anything
else is a plus.
As regards the links you gave: the first is the project wiki, which
accords fully with my earlier statements; the second is an attempt at a
‘guide to the guide’, which should not be necessary. If a guide itself
needs a guide, there is something wrong. Isn’t this obvious?
The second is not a guide to a guide. It is Step 2. It refers to the
‘guide’ for installation - and adds something new. Tells you how you
could create a project and get moving in detail. Together, the 2
documents help get you started.
Again, the second link does something about the problem - if it’s felt
that there was something missing in the original docs, an attempt is
being made to address it. That’s better than shouting doom from atop an
email client.
Whoa, you’re a bit prickly on this one! Fair enough, it’s not a guide to
the guide - but I still don’t think it should exist (in a perfect world
of course, and we’re a long way from that). At any rate, I don’t think
there should be major holes in the main manual, like connecting to
databases and stuff.
A couple of other points in your post I didn’t answer, this is enough
for now I think. Once again, if what I say makes any sense to you - then
I will help further.
I find your attitude a bit dismissive, but I’ll overlook that assuming
that you know more than me (which is still TBD).
Well, if you think that, it’s come out wrong. My attitude is certainly
critical, as to argue a point you must often criticise. But dismissive?
I’m trying to engage, and spending some time on it. I don’t think that
qualifies.
Trouble is, criticism is painful - and most of us think we don’t need
it. If I say something can be improved, and offer some help, does that
make me dismissive? Up to you I guess - I must be putting it the wrong
way or something.
I don’t claim to know any more about anything than anyone else, I simply
have an opinion and am usually prepared to back it up - otherwise what’s
the point. I’m happy to try and prove any statement I make, though over
a beer is best.
I think you could progress those docs by starting with a bunch of
definitions, of what you can and can’t do with the app, and where it can
or can’t be installed. To me that just seems logical, but I guess
everyone thinks differently. I’m a usability guy, and if something isn’t
really straightforward it niggles me I suppose. A big problem for me is
that developers know everything about the way applications work, and
just assume everyone else will be OK. That winds me up.
Good luck anyway.
Chris
