7 replies to this topic

[oeed]

So I've be working away in whatever little time I've had recently on an OS X app that lets you add widgets to your desktop. You can make your own pretty easily using HTML, CSS and JS. To make it as easy and popular as possible I naturally want to have really good documentation for it.

Does anyone have any suggestions for good (preferably free) services for providing documentation? I'm considering GitHub, although the app itself will be closed source and not free, I could put examples on there and use the wiki. I'm happy/somewhat wanting people to be able to edit them. One issue with GitHub is that it would feel a bit isolated or fragmented from the main site.

I also really want to make sure it's really thorough, unlike that somewhat neglected Bedrock docs (which I'd probably also like to move to whatever platform is suggested). Being able to have images will be a must too.

Thoughts?

Edited by oeed, 06 April 2015 - 06:27 AM.

[kornichen]

Maybe you can use MediaWiki or another Wiki software. Users would be able to edit every page you allow them to and you can control changes thanks to the version history of every page. Furthermore you can change the design of the Wiki that it looks like your main site.

Edited by kornichen, 06 April 2015 - 09:22 AM.

[oeed]

kornichen, on 06 April 2015 - 09:22 AM, said:

Maybe you can use MediaWiki or another Wiki software. Users would be able to edit every page you allow them to and you can control changes thanks to the version history of every page. Furthermore you can change the design of the Wiki that it looks like your main site.

Well, I mean MediaWiki is isn't really designed for this purpose it? I certainly won't rule it out, but I haven't really seen many/any documentation on a MediaWiki site. But hey, not saying not to anything.

Also, with your quote, if it were me I'd instead say "If you can't make it good, fire everyone who's stopping you from doing so..." I mean... come on Bill. Ala my quote.

Edited by oeed, 06 April 2015 - 09:27 AM.

[Lupus590]

have a look at this

http://en.wikipedia.org/wiki/Doxygen

[oeed]

Lupus590, on 06 April 2015 - 10:08 AM, said:

have a look at this

http://en.wikipedia.org/wiki/Doxygen

At least according to that page, it doesn't support JavaScript. Doing it automatically won't really work anyway as I'm dynamically exposing sandboxed Objective-C classes to JavaScript, so the API isn't actually written in JavaScript but you call it through JavaScript.

Thanks for the suggestion though, I might actually look in to a similar thing for Bedrock if it exists for Lua.

[Bomb Bloke]

In regards to actually creating the documentation, are you familiar with javadoc? It's used to generate eg this stuff. It wouldn't surprise me if something similar is available for whatever language you're working with. Dig around the website of whoever supports that language, see what they recommend for producing documentation.

In regards to hosting, assuming you can't auto-generate your docs, MediaWiki is an excellent way of presenting information of any kind.

[SquidDev]

oeed, on 06 April 2015 - 10:11 AM, said:

Thanks for the suggestion though, I might actually look in to a similar thing for Bedrock if it exists for Lua.

I've used LDoc in the past with great success. You can't run it in CC's Lua but it is pretty flexible.

[Lupus590]

SquidDev, on 06 April 2015 - 01:13 PM, said:

oeed, on 06 April 2015 - 10:11 AM, said:

Thanks for the suggestion though, I might actually look in to a similar thing for Bedrock if it exists for Lua.

I've used LDoc in the past with great success. You can't run it in CC's Lua but it is pretty flexible.

Looks like I may end up with another project, a CC version of LDoc.

Edit: I can't believe I'm actually starting this

Edited by Lupus590, 06 April 2015 - 02:58 PM.