Online doxygen/Javadoc documentation
-
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.
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.
Cédric Moonen Software developer
Charting control [v1.5] OpenGL game tutorial in C++ -
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.
Cédric Moonen Software developer
Charting control [v1.5] OpenGL game tutorial in C++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.
-
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.
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 ;P
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 :-O
Cédric Moonen Software developer
Charting control [v1.5] OpenGL game tutorial in C++ -
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 ;P
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 :-O
Cédric Moonen Software developer
Charting control [v1.5] OpenGL game tutorial in C++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.
-
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.
Pete O'Hanlon wrote:
The reason I don't do this: MSDN
:laugh: 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.
Cédric Moonen Software developer
Charting control [v1.5] OpenGL game tutorial in C++ -
Pete O'Hanlon wrote:
The reason I don't do this: MSDN
:laugh: 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.
Cédric Moonen Software developer
Charting control [v1.5] OpenGL game tutorial in C++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.
-
Hello Chris, For some articles it could be usefull to have a link to a online doxygen or javadoc documentation. For one of my article, I plan to provide a zip file containing doxygen documentation instead of documenting every classes and functions in the article itself. I think it could be nice for people to also be able to browse the documentation online (and not need to first download the zip and unzip it). Do you think it could be a usefull feature ?
Cédric Moonen Software developer
Charting control [v1.5] OpenGL game tutorial in C++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. :thumbsup:
Best wishes, Hans
[CodeProject Forum Guidelines] [How To Ask A Question] [My Articles]
-
Hello Chris, For some articles it could be usefull to have a link to a online doxygen or javadoc documentation. For one of my article, I plan to provide a zip file containing doxygen documentation instead of documenting every classes and functions in the article itself. I think it could be nice for people to also be able to browse the documentation online (and not need to first download the zip and unzip it). Do you think it could be a usefull feature ?
Cédric Moonen Software developer
Charting control [v1.5] OpenGL game tutorial in C++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
-
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.
Cédric Moonen Software developer
Charting control [v1.5] OpenGL game tutorial in C++ -
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.
Cédric Moonen Software developer
Charting control [v1.5] OpenGL game tutorial in C++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
-
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.
Cédric Moonen Software developer
Charting control [v2.0] OpenGL game tutorial in C++