How Adobe Could Tie Blogs and Livedocs
ColdFusionThere has been a lot of excellent blog posts about ColdFusion 8 by bloggers such as Ray Camden, Ben Nadel, Ben Forta, Ashwin Mathew, and many, many more, indeed Ahamed on the CF team has two blogs. Most of this content now lives, for all intents and purposes, in the the world of Google (or other search engines).
Could Adobe make this content more accessible?
Of course! Here are two new, related features to livedocs that I think would be a great addition, and not just for ColdFusion, its the same for all the great Flex, Flash and other Adobe related blogs.
- Add a blog/other sources section on livedocs for each tag and function. Anyone could submit a blog entry to this section and once submitted the title and a link to the entry would show up. Other sources would include knowledge based articles and other content from the Adobe web site.
- Users of livedocs could rate a blog entry as useful or flag it as not appropriate. Over time the more useful entries would rise to the top while anything flagged could be looked at by a person and deleted if needed.
I think the ColdFusion documentation is very good. The purpose of adding blog entries to livedocs would be to compliment it and create one central place that has everything related to cfquery or any other tag or function.
Adam Fortuna said:
What would be pretty slick would be trackbacks as well. Just post a link to the tag you're talking about then that post would show up on the livedocs.
The downside would be the huge amount of spam they'd get, and the time needed to sift through it all though. :(
The downside would be the huge amount of spam they'd get, and the time needed to sift through it all though. :(
barry.b said:
Sam, I *mostly* agree with you...
"I think the ColdFusion documentation is very good."
agreed. Not only that but there's a lot of it. People don't realise just how much is available. It's not just the reference stuff, it's how to use it.
"adding blog entries to livedocs would be to compliment it"
yes, by putting it into context which is invaluable in understanding the finer details. Also multiple examples to really nail the point. and don't forget the blog comments that can lead to further solutions or ideas.
two points I'd like to raise however:
adding references to external sites - blogs outside of Adobe's control - can be a dangerous thing. What happens if Ray Camden or Charlie Arehart change their domain names? broken links. You might be lucky enough that search engines will find them again but you're almost looking for a service level agreement that these entries will exist "as-is" for ever and a day. For a business that could be either restrictive or risky.
I'd also like to throw up an almost off topic point: that the exellent documentation may be harming both technical book sales (like CF) and user group turn-outs. Why buy a book if you don't need to, if the official supplied docs gives you what you want? Why go to your local CFUG with a problem if the docs (and blogs) solve the problem for you? I suppose the same infrence can be made with discussion forums too. The problems have been solved a dozen times over (except for new stuff).
just my 2c, love to hear you thoughts on these points
"I think the ColdFusion documentation is very good."
agreed. Not only that but there's a lot of it. People don't realise just how much is available. It's not just the reference stuff, it's how to use it.
"adding blog entries to livedocs would be to compliment it"
yes, by putting it into context which is invaluable in understanding the finer details. Also multiple examples to really nail the point. and don't forget the blog comments that can lead to further solutions or ideas.
two points I'd like to raise however:
adding references to external sites - blogs outside of Adobe's control - can be a dangerous thing. What happens if Ray Camden or Charlie Arehart change their domain names? broken links. You might be lucky enough that search engines will find them again but you're almost looking for a service level agreement that these entries will exist "as-is" for ever and a day. For a business that could be either restrictive or risky.
I'd also like to throw up an almost off topic point: that the exellent documentation may be harming both technical book sales (like CF) and user group turn-outs. Why buy a book if you don't need to, if the official supplied docs gives you what you want? Why go to your local CFUG with a problem if the docs (and blogs) solve the problem for you? I suppose the same infrence can be made with discussion forums too. The problems have been solved a dozen times over (except for new stuff).
just my 2c, love to hear you thoughts on these points
Sam Farmer said:
@Adam: Good points. Maybe you could only post from an approved url? I don't know a great deal about feedbacks though.
@Barry B: They could run a link checker and if your links fails, say, 5 days in a row then it would be removed.
I completely agree with your point about the quality of CF documentation and the lack of technical books.
@Barry B: They could run a link checker and if your links fails, say, 5 days in a row then it would be removed.
I completely agree with your point about the quality of CF documentation and the lack of technical books.
charlie arehart said:
I think that's a very interesting idea, Sam. Barry's points are fair (and thanks very much for the mention), but maybe Adobe's reluctance could point to an alternative: perhaps instead Jake Munson's cfquickdocs.com could take on this role.
Since he already uses both the livedocs and even shows their comments at the bottom, it could become a cool repository for such links and backlinks.
I had had in mind creating something to help with this very dilemma, but maybe rather than have some "yet other" repository, it may make more sense to have it done somewhere already recognized as a defacto 3rd party doc site. I'll point Jake to this entry to hear what he has to say.
If he's not interested, then perhaps this could be resolved by creating a new community-driven resource. It would take quite a bit of work finding and adding such links, or reviewing those proposed by others. Still, I think it would be a very useful resource. We can't all follow every entry of every blogger, and something really valuable may slip by us.
Since he already uses both the livedocs and even shows their comments at the bottom, it could become a cool repository for such links and backlinks.
I had had in mind creating something to help with this very dilemma, but maybe rather than have some "yet other" repository, it may make more sense to have it done somewhere already recognized as a defacto 3rd party doc site. I'll point Jake to this entry to hear what he has to say.
If he's not interested, then perhaps this could be resolved by creating a new community-driven resource. It would take quite a bit of work finding and adding such links, or reviewing those proposed by others. Still, I think it would be a very useful resource. We can't all follow every entry of every blogger, and something really valuable may slip by us.
charlie arehart said:
I just thought of another possibility: even if Jake doesn't want to take on the responsibility to create and manager such a resource, he may be willing to do something like how he grabs the comments from livedocs. He could grab a feed from some resource like this that someone else does.
I was thinking that a wiki may be the way to go for such a central, community-managed resource.
And if any might complain that they felt the pages were getting too long in quickdocs because of this (hampering its name-sake purpose), perhaps it could be a configurable option whether to show such a feed.
I was thinking that a wiki may be the way to go for such a central, community-managed resource.
And if any might complain that they felt the pages were getting too long in quickdocs because of this (hampering its name-sake purpose), perhaps it could be a configurable option whether to show such a feed.
Jake Munson said:
I agree, Charlie. That would be a fun addition to CFQuickDocs. It wouldn't be too hard to do either, if I allowed people to submit posts as you suggested. Then I could just store then in a DB, and then display them as a separate section at the bottom of the relevant doc entry.
Problem is, I've got a lot of things I need to work on right now. I've considered making CFQuickDocs open source (even blogged about it once), but I'm not sure if anybody would be willing to help. A couple of people have offered to help me privately lately, and I've given them the code, but nobody has given me any "patches" yet. Oh well...
Problem is, I've got a lot of things I need to work on right now. I've considered making CFQuickDocs open source (even blogged about it once), but I'm not sure if anybody would be willing to help. A couple of people have offered to help me privately lately, and I've given them the code, but nobody has given me any "patches" yet. Oh well...
Sean Corfield said:
Livedocs serves up arbitrary HTML docs with no regard to content so, other than tagging pages with comments, Livedocs has no idea about tags and functions for example. Bear in mind that the Livedocs system serves up all sorts of product documentation as well as the Web Team's coding guidelines.
Much as I love Livedocs (I helped design two different versions - of the four incarnations so far), I think that Sam's suggestions would be more appropriate for cfQuickDocs since that focuses on tags and functions (the CFML Reference doc - and ignores all the other CFML docs).
Much as I love Livedocs (I helped design two different versions - of the four incarnations so far), I think that Sam's suggestions would be more appropriate for cfQuickDocs since that focuses on tags and functions (the CFML Reference doc - and ignores all the other CFML docs).
Sam Farmer said:
@Sean, I love livedocs and have used it extensively since CF5 (was it on livedocs?) it whatever version was first on livedocs. So, a belated thanks for your work on it. I just think with the internet being what it is that the definition of "live" will continually evolve over the years.
While my suggestion is geared towards tags and functions there is no reason to stop there. Based on your insight it sounds like my suggestion would be quite an undertaking, but as we are on the fourth version of livedocs maybe it could make the next one. And I know you are not on that team anymore just wanted to throw it out there.
While my suggestion is geared towards tags and functions there is no reason to stop there. Based on your insight it sounds like my suggestion would be quite an undertaking, but as we are on the fourth version of livedocs maybe it could make the next one. And I know you are not on that team anymore just wanted to throw it out there.
Loading....