A challenge from a CMS implementer

rubyonrails-talk
21

Chris Price wrote:

1: Engineers cannot communicate. This is a universal truth, always has been, and will never change. They need interpreters.   

...and they would be glad to have that.

Unless you know of specific circumstances why the Radiant project would not align with these axioms, even though it may be painful to do so, you should assume that the previous statements apply.   

For one, I have actually seen, read and followed the documentation on the Radiant CMS website.

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.

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.

Let's say this is the Installation doc, for implementing and commissioning personnel - we state this first.

Then we state what the software is, then what broad class it is, then any sub-category it may belong to; then how it can be used, with any immediately relevant pros or cons; then what machinery it will work on and what it won't; how it can and can't be installed; what are the required pre-requisites if any; any major advantages or disadvantages to the approach this application takes. So you start with a very firm idea of exactly what you are looking at, and you don't get any nasty surprises later when you find it won't install on your Sun Solaris/ Unix/ Oracle. Radiant doesn't do this.

For instance, then, you could say (but with much expansion): RadiantCMS is a website content management system [that tells us what it is and also the class - not an Intranet or documentation content mechanism] that can be used as a [delete as appropriate] provider-consumer CMS community/ news CMS portal CMS.

It can be installed: remotely via FTP and HTTP remotely or on the local machine on the local machine only

It requires a server that is enabled for: etc -------------------------------

....and this is just the first page. Not sure if you get the picture but 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

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.

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.

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.

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).

Best Regards Mohit.

22

Documentation: I'm not sure if you're aware of this but two facts are pertinent here:

1: Engineers cannot communicate. This is a universal truth, always has been, and will never change. They need interpreters.

Of course engineers can communicate. The people who work to route traffic around the internet as their daily job are very capable people behalf, that you would propose such an utterly false statement.

2: Open-source documentation is famous the world over for being absolutely, utterly terrible. This is related to point 1.

I find most open source documentation to be adequate. Some is of course better than some others, but that's true with all documentation, open or proprietary. I've not found it difficult to maintain a 12 year developer career using open source technology almost exclusively. So your premise, at least for myself, is false. I'm sure others would agree.

Software authors usually write the docs for OSS projects, but you can see they are not a good choice for this task.

These facts

These are not facts, they are your own flawed opinions. Flawed mostly due to your own apparent lack of experience with what you choose to discuss.

are part of the reason why commercial enterprises are so very reluctant to take on OSS for business software use. They are fully

Commercial enterprise (software) is scared of what it cannot control.

prepared to pay more for software that is not as good, when it is commercially backed - ie with good documentation, training, training support, and technical support.

If open source does not suite you then leave it alone. No one is holding a gun to your head.

23

Mohit Sindhwani wrote:

Chris Price 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: 1. What servers the app will/ will not run on. 2. 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: 1. 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. 2. 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

24

Greg

Your points:

Greg Donald wrote:

Documentation: I'm not sure if you're aware of this but two facts are pertinent here:

1: Engineers cannot communicate. This is a universal truth, always has been, and will never change. They need interpreters.

Of course engineers can communicate. The people who work to route traffic around the internet as their daily job are very capable people from my experience. I find it quite insulting, if only on their behalf, that you would propose such an utterly false statement.

Greg, I need to tell you that I am an old engineer - very old. I've worked in many branches of engineering (was going to say nearly all, but that would be crazy). I've seen it all. Haven't done it all yet though. I found that I spent an increasing amount of time writing stuff, and went with it.

I can understand if you are a young man, and have never heard this statement before - but believe me, it applies almost generally and of course it is normally only spoken behind technicians' backs. Naturally there are exceptions but that's true of anything - I'm a techie who writes (or thinks he can) so there you go. But I'm not insulting myself or other engineers by repeating this truism, because you'll find it's correct more often than not. So what - you think people can do everything?

2: Open-source documentation is famous the world over for being absolutely, utterly terrible. This is related to point 1.

I find most open source documentation to be adequate. Some is of course better than some others, but that's true with all documentation, open or proprietary. I've not found it difficult to maintain a 12 year developer career using open source technology almost exclusively. So your premise, at least for myself, is false. I'm sure others would agree.

I works for you, fine. I'd suggest that might be because you are a talented dev and understand it all without your hand being held. That doesn't apply to me or many others.

If you make a living in the OSS/ commercial-user world, that's terrific. A lot of us would like to do the same, and perhaps only partially succeed there at present. I believe this market will expand, though - and it particularly suits the technically gifted such as yourself, no doubt.

Software authors usually write the docs for OSS projects, but you can see they are not a good choice for this task.

These facts

These are not facts, they are your own flawed opinions. Flawed mostly due to your own apparent lack of experience with what you choose to discuss.

Well, OK, you don't agree. But I'm an old guy and I've been around, so I can say with confidence that tech staff are best at doing what they do, and others better at filling in the gaps; but there are exceptions to every rule. Above all, it is not insulting to say that people are generally good at doing what they do, and frequently poor to bad at other tasks. Why would you assume that an engineer is going to be brilliant at at some other task vaguely related in some way to his products?

Most enterprises find they need spec iali sts for doing the work, spe cia lists to write the user and training manuals, and speci alis ts to market the results. Developers originate everything in this field - but to think they are capable of doing an expert job on every aspect of the project or its use in the field is a flawed concept. They are clever people, but everyone has to spec ialise now. There may indeed be people who can do two or three others' jobs well, but they are not a majority.

are part of the reason why commercial enterprises are so very reluctant to take on OSS for business software use. They are fully

Commercial enterprise (software) is scared of what it cannot control.

Yes, no doubt.

prepared to pay more for software that is not as good, when it is commercially backed - ie with good documentation, training, training support, and technical support.

If open source does not suite you then leave it alone. No one is holding a gun to your head.

OK, agreed. But what I am saying is that it is often a first-class product, why not present it and market it better.

Please, let's agree to disagree. I believe that devs do a good job but need help presenting their work to a wider audience.

Chris

25

Chris,

Even though you really got a lively discussion, I think your request doesn't fit this community very well.

Rails is absolutely awesome, but it is a tool for developers to get what they want easily, well-done and having fun. It is not a panacea for the web projects of commercial enterprises. That's Microsoft!

Cheers, Sazima

26

Sazima

Yeah, it's been fun!

Bit of a mistake on my part, though, coming here and talking about code...

Still, I make at least one mistake a day, and this was one I guess. I'm not a coder and really don't appreciate a lot of the issues, of course. When you get older, it's easier to admit your abilities are limited.

Normally I've got a smile on my face and I'm always willing to help anyone - but that doesn't transmit well I suppose.

Anyway.

Chris

27

Mohit Sindhwani wrote:

understand what the problem is. There's a TinyMCE plugin for Radiant (though I don't like to use WYSIWIG for a CMS but again, to each his own) and there's also a WYMEditor plugin for it (if I remember

Mohit,

Where can I find that TinyMCE plugin for Radiant? I'm working on a project where I need non-technical types to edit page content while I'm working on other aspects of the project.

If I can put together a WYSIWIG editor allowing them to add/modify content, the project will speed up.

With Regards,

Cody Skidmore

28

Cody Skidmore wrote:

Mohit,

Where can I find that TinyMCE plugin for Radiant? I'm working on a project where I need non-technical types to edit page content while I'm working on other aspects of the project.

If I can put together a WYSIWIG editor allowing them to add/modify content, the project will speed up.

With Regards,

Cody Skidmore    Hi Cody,

There are 2 WYSIWIG and 1 WYSIWYM Text Editor plugins for Radiant:

* WYSIWYG Text Editor (TinyMCE) (archive, docs)     A WYSIWYG editor based on the TinyMCE editor * WYSIWYG Text Editor (FCKeditor) (home, packages, svn)     A WYSIWYG editor based on the FCKeditor * WYSIWYM Text Editor (WYMeditor) (home, svn)     Adds WYMeditor as a text filter. Requires the shards extension

The page to start with is: http://wiki.radiantcms.org/Thirdparty_Extensions

Hope this helps.

Cheers, Mohit. 1/18/2008 | 11:16 PM.

29

Mohit Sindhwani wrote:

Hope this helps.

It does. Thank you Sir!

30

Chris,

You're doing a lot of whining and not enough contribution. Do something about the problems you preceive or relax and stop wasting breath (or bits) in this case.

And if you think you don't want to contribute and that rails is unacceptable in it's current form... use php or java or .net or whatever floats your boat

Thanks for stopping by.

~ mel

31

Melvin Ram wrote:

Chris,

You're doing a lot of whining and not enough contribution. Do something about the problems you preceive or relax and stop wasting breath (or bits) in this case.

And if you think you don't want to contribute and that rails is unacceptable in it's current form... use php or java or .net or whatever floats your boat

Thanks for stopping by.

Understood. I stopped by for a chat and I've had my money's worth :slight_smile:

My offer to Mohit is open if he is interested, maybe you didn't see that.

As regards code and its relative merits - I'm not a coder and don't know enough to get involved with that argument. I have to deal with the end results in my work, though, and have strong opinions on that side of it. Am looking forward to more RoR coming along, to see how that works out in my space.

Chris

32

Chris Price wrote:

Understood. I stopped by for a chat and I've had my money's worth :slight_smile:

My offer to Mohit is open if he is interested, maybe you didn't see that.

As regards code and its relative merits - I'm not a coder and don't know enough to get involved with that argument. I have to deal with the end results in my work, though, and have strong opinions on that side of it. Am looking forward to more RoR coming along, to see how that works out in my space.

Chris (Price),

Not sure if you're still around on this list, but there's an ongoing project now on the Radiant CMS site for creating user documentation. If you have the chance, take a look - http://wiki.radiantcms.org/Summer_Reboot and if you have the time, it would be great to have your opinions.

Of course, this invitation applies to everyone here. We're trying to create documentation for Radiant and its commonly used extensions so that it's more broadly applicable to a larger audience. If you're keen, just log on - http://wiki.radiantcms.org/Summer_Reboot

Cheers, Mohit. 8/18/2008 | 1:58 AM.