Creating a documentation

[Corthezz]

Hey there,
I am about to create an online documentation for a c# class. Currently planing on using GhostDoc to generate XML comments and SHFB to create the hml files from the XML.
Stil I want to ask if someone maybe knows a better solution.
I am very impressed with Honorbuddys documentation since its very clear. Does someone maybe know what tools they use?

Thanks

[Torpedoes]

Hey there,
I am about to create an online documentation for a c# class. Currently planing on using GhostDoc to generate XML comments and SHFB to create the hml files from the XML.
Stil I want to ask if someone maybe knows a better solution.
I am very impressed with Honorbuddys documentation since its very clear. Does someone maybe know what tools they use?

Well I don't know much about GhostDoc or any of the other generating tools but I do know that HonorBuddy's documentation sucks and if you're impressed with it, you need to raise your standards. It's poorly written, it looks awful and it's incomplete. If you're going to automatically generate documentation then why even have documentation. My suggestion is if you're serious about your project, write all the documentation yourself and make a dedicated website for it, or maybe use a wiki on GitHub. But if you're lazy I guess you can generate webpages using documentation generators, though I've seen enough of them to know they're garbage.

For my own project I'm developing a dedicated website with detailed documentation which I'm writing myself. I use node.js with plugins that help me generate static webpages through the use of templates. Some documentation uses markdown, other uses custom generators. Either way it looks great and although it takes time, it's well worth the effort. But each project is different, figure out if it's worth the effort, but don't half ass it, never half ass it. Good Luck!

[Valediction]

Well I don't know much about GhostDoc or any of the other generating tools but I do know that HonorBuddy's documentation sucks and if you're impressed with it, you need to raise your standards. It's poorly written, it looks awful and it's incomplete. If you're going to automatically generate documentation then why even have documentation. My suggestion is if you're serious about your project, write all the documentation yourself and make a dedicated website for it, or maybe use a wiki on GitHub. But if you're lazy I guess you can generate webpages using documentation generators, though I've seen enough of them to know they're garbage.

For my own project I'm developing a dedicated website with detailed documentation which I'm writing myself. I use node.js with plugins that help me generate static webpages through the use of templates. Some documentation uses markdown, other uses custom generators. Either way it looks great and although it takes time, it's well worth the effort. But each project is different, figure out if it's worth the effort, but don't half ass it, never half ass it. Good Luck!

Are you telling me you've never had to use Javadoc for anything? Or didn't find it useful? Well assuming you have done anything in Java of course (for some of us it's a necessary evil :/ ). For many projects (typically medium to large), it seems a very apt tool and choice, taking into account the time/quality tradeoff.

[Torpedoes]

Are you telling me you've never had to use Javadoc for anything? Or didn't find it useful? Well assuming you have done anything in Java of course (for some of us it's a necessary evil :/ ). For many projects (typically medium to large), it seems a very apt tool and choice, taking into account the time/quality tradeoff.

Last time I used Java was when it was still owned by Sun.

The problem with all these generating tools (Javadoc, Doxygen, VC) is that they encourage writing bad documentation. All those comment blocks need to be formatted, they're often limited in functionality and they get in the way of well written, clean code. The generators also don't create particularly well designed pages. In an effort to conform to "standards" they include a bunch of extra crap that nobody cares about, and in some cases they end up looking like a jumbled mess. They were developed by engineers not designers. All projects are unique and, as such, deserve a unique approach to documentation. Just because something is there doesn't mean you should use it (except when it comes to security).

But then again I think I'm just irked by all the documentation I've seen. All of them are just a pain in the ass to navigate and some offer no useful information.

[Jadd]

HB are most certainly using SHFB. If yours looks any different then it's probably because you're using an old release (maybe from codeplex, those are outdated.)

Edit: By the way some of their documentation looks, they are also using something like GhostDoc to document a lot of functions, ie. LevelBot.MountVendor "Mounts the vendor"...

[Filint]

HB are most certainly using SHFB. If yours looks any different then it's probably because you're using an old release (maybe from codeplex, those are outdated.)

Edit: By the way some of their documentation looks, they are also using something like GhostDoc to document a lot of functions, ie. LevelBot.MountVendor "Mounts the vendor"...

I've just looked through lots of their documentation.

Good god. I haven't laughed so much in years.