|
The whole point of an article is to sell me on your idea. If I can't get enough detail from reading the article then the article has not served its purpose - adding API docs is hardly going to sell me on the idea that should have come across by reading a well written article.
"WPF has many lovers. It's a veritable porn star!" - Josh Smith As Braveheart once said, "You can take our freedom but you'll never take our Hobnobs!" - Martin Hughes.
My blog | My articles | MoXAML PowerToys
|
|
|
|
|
Pete O'Hanlon wrote: The whole point of an article is to sell me on your idea.
It really depends of the kind of article you submit. If the article is about a concept (design pattern, ideas, ...), then I agree with you. But if you submit an article as a kind of library or control (e.g. the MFC grid control from Chris), then things are a bit different: the article should contain enough information to be able to use the control properly, not only convince people that it's a good control
Pete O'Hanlon wrote: adding API docs is hardly going to sell me on the idea that should have come across by reading a well written article.
I totally agree, that's why putting the API documentation inside the article makes it heavy and is unecessary there. But you need to supply it anyway because if people want to use your control, they need to have it. And in general, it is a bit more easier to simply have a link to the API documentation instead of downloading a zip file.
|
|
|
|
|
I come from the angle that the well written article will make me want to download the code and investigate it myself. There are many things that I've downloaded in the past which have no earthly use for me, but the article has interested me enough to want to learn more.
Maybe I'm just freaky this way, but no matter how well documented the API is, if the article doesn't convince me that the control fits the bill, then I won't bother downloading it (and yes - I did download your charting control because of the article, even though I don't do C++ any more).
"WPF has many lovers. It's a veritable porn star!" - Josh Smith As Braveheart once said, "You can take our freedom but you'll never take our Hobnobs!" - Martin Hughes.
My blog | My articles | MoXAML PowerToys
|
|
|
|
|
In fact we both agree: I also think an article should be well written enough to convince me to use the control (or the library). But on the other hand, once I made my mind to use a specific control and start using it, I tend to prefer browsing online documentation rather than downloading it.
Anyway, it's not really important: having to download the documentation is not really a big effort
Pete O'Hanlon wrote: and yes - I did download your charting control because of the article, even though I don't do C++ any more
Thanks
|
|
|
|
|
Cedric Moonen wrote: I tend to prefer browsing online documentation rather than downloading it.
The reason I don't do this: MSDN. I suppose that's an unfair example, but I find MSDN to be unwieldy and intrusive.
"WPF has many lovers. It's a veritable porn star!" - Josh Smith As Braveheart once said, "You can take our freedom but you'll never take our Hobnobs!" - Martin Hughes.
My blog | My articles | MoXAML PowerToys
|
|
|
|
|
Pete O'Hanlon wrote: The reason I don't do this: MSDN
Well, yeah it is a very bad example. I've used some open source libraries and a lot of them provides some kind of API doucmentation (in general doxygen or Javadoc). When done correctly (and that's not too difficult to do), it is a very valuable tool. Of course, on its own it is not enough: you have to provide some overview tutorials so that people have a broad overview of the library. But after that people need to be able to search for detailed information about a specific part of the library. That's what I am thinking about: the article contains the tutorial and overview, and along with the article you supply the API documentation.
Did you already use doxygen (or javadoc) generated documentation ? It's something I could not live without for a lot of libraries that I'm using.
|
|
|
|
|
I've used Doxygen, and I've used Sandcastle. I don't really have a preference.
"WPF has many lovers. It's a veritable porn star!" - Josh Smith As Braveheart once said, "You can take our freedom but you'll never take our Hobnobs!" - Martin Hughes.
My blog | My articles | MoXAML PowerToys
|
|
|
|
|
That's an interesting idea. Sometimes I include tables of APIs in my articles, but obviously the Doxygen output would be better.
Maybe a button that says Explore this API in Doxygen? Or maybe a new class of article, or new section, called The Reference Set.
This could add a new depth to CodeProject, make it more than just a drive-by grab-an-article-type site.
Worth thinking about.
|
|
|
|
|
You can already link to an online doc (or include a downloadable version). I think Hans has spotted that there is scope here to do better.
Maybe a separate page that is purely an API page for an article? Not universally relevant, but could be handy.
cheers,
Chris Maunder
The Code Project Co-founder
Microsoft C++ MVP
|
|
|
|
|
Chris Maunder wrote: You can already link to an online doc
Yes, but this page has to be online. So, my idea was to simply be able to upload some other pages that you can link from your article. In fact, doxygen and javadoc both generate mutliple html pages and one index page.
|
|
|
|
|
Would something as simple as allowing you to have "child" articles do the trick? I'm not keen on allowing straight HTML documents to be uploaded and served from our site because of the security issues (hosting ActiveX controls, phishing etc) but child articles, to which you could link to, may help? Maybe?
cheers,
Chris Maunder
The Code Project Co-founder
Microsoft C++ MVP
|
|
|
|
|
Yes, that would be an improvement. This could be for instance nice if you have a very large article that you could divide into section and have an introduction and a table of content on the root page. But it is not really a need though.
On the other hand, I don't think it will be possible to host generated documentation this way. Anyway, what I did is that I simply attached a zip file containing the generated documentation along my article.
|
|
|
|
|
Chris, I just got one of those empty forum pages at http://www.codeproject.com/script/Forums/View.aspx?fid=1649&fr=26#xx0xx[^]
I was reading, not writing or editing, several messages on page 1; when I reached the bottom I clicked
"next" and got an empty page (i.e. normal forum page however with zero messages); footer says Web12.
Not sure how I can help by providing more, looking at something in particular, ... I do have a screen shot, if you want it ask for +CodeProject_C_Discussion_Boards_Free_source_code_and_programming_help_Mozilla_Firefox_20090312_031833.jpg
Luc Pattyn [Forum Guidelines] [My Articles]
- before you ask a question here, search CodeProject, then Google
- the quality and detail of your question reflects on the effectiveness of the help you are likely to get
- use the code block button (PRE tags) to preserve formatting when showing multi-line code snippets
|
|
|
|
|
I'm seeing it again, too, usually after I edit a post.
"Why don't you tie a kerosene-soaked rag around your ankles so the ants won't climb up and eat your candy ass..." - Dale Earnhardt, 1997 ----- "...the staggering layers of obscenity in your statement make it a work of art on so many levels." - Jason Jystad, 10/26/2001
|
|
|
|
|
I've managed to replicate it but not repeatidly or consistently. I'm having another crack at tracking it down now.
cheers,
Chris Maunder
CodeProject.com : C++ MVP
|
|
|
|
|
Chris, I just had a new experience: in VB forum, in a thread at the bottom of a page, I added my reply and when I clicked "post message", the forum page came back, but my reply was not on it, it was now the first message on the next page. That is not ideal but it struck me as I do not recall having had that happen to me ever before. Since it might be related to the empty forum phenomenon I thought I'd report it.
Luc Pattyn [Forum Guidelines] [My Articles]
- before you ask a question here, search CodeProject, then Google
- the quality and detail of your question reflects on the effectiveness of the help you are likely to get
- use the code block button (PRE tags) to preserve formatting when showing multi-line code snippets
|
|
|
|
|
I've just uploaded the new code so let's keep our fingers crossed.
cheers,
Chris Maunder
CodeProject.com : C++ MVP
|
|
|
|
|
Chris Maunder wrote: let's keep our fingers crossed
Not sure how long you can do that.
The good thing is I am now capable of sending myself an e-mail reply. I wouldn't mind you providing some insight in what went wrong before... always eager to learn.
Thanks.
Luc Pattyn [Forum Guidelines] [My Articles]
- before you ask a question here, search CodeProject, then Google
- the quality and detail of your question reflects on the effectiveness of the help you are likely to get
- use the code block button (PRE tags) to preserve formatting when showing multi-line code snippets
|
|
|
|
|
I just experienced a similar thing. I edited one of my posts and all I can see is a lounge without any messages. I was on page 9 and certainly it was not the last page. I could see only the 1st page with all the messages. None of the later pages were showing messages.
|
|
|
|
|
How many messages per page do you have set?
cheers,
Chris Maunder
The Code Project Co-founder
Microsoft C++ MVP
|
|
|
|
|
25...I have the screen shot if that is of any help. I could not find where to put that though
|
|
|
|
|
No need - I just experienced the issue myself and have narrowed it down a little.
Thanks!
cheers,
Chris Maunder
The Code Project Co-founder
Microsoft C++ MVP
|
|
|
|
|
The homepage right now contains an article-needing-approval[^] dated 12-MAR, while it still is 11-MAR overhere for the next 15 minutes. Wasn't the idea to always show datetime local to the viewer?
Luc Pattyn [Forum Guidelines] [My Articles]
- before you ask a question here, search CodeProject, then Google
- the quality and detail of your question reflects on the effectiveness of the help you are likely to get
- use the code block button (PRE tags) to preserve formatting when showing multi-line code snippets
|
|
|
|
|
what's your timezone? Are you in or out of daylight savings? (You can set this in your profile)
cheers,
Chris Maunder
CodeProject.com : C++ MVP
|
|
|
|
|
I'm in Antwerp, Belgium, that's GMT+1
My CP settings currently are GMT+1 and "Are you currently in Daylight Saving Time?" unchecked.
Don't know how to interpret that, I would hope it works automatically, Windows knows we haven't switched to "summer time" yet. Are you saying I should change the setting twice a year?
ADDED: message changed at 1:02 local time to watch how it gets timestamped.
Luc Pattyn [Forum Guidelines] [My Articles]
- before you ask a question here, search CodeProject, then Google
- the quality and detail of your question reflects on the effectiveness of the help you are likely to get
- use the code block button (PRE tags) to preserve formatting when showing multi-line code snippets
modified on Wednesday, March 11, 2009 8:02 PM
|
|
|
|