How do I document this shit?

#1 I don't see a problem with using our own websites as long as we have a central location to collect links to all that stuff. For example, I'm personally inclined not to accept your safari into the T3D wiki, but to add a big list of links to it and link to your own website if you'd put the safari on that. Basically, codifying the forum thread you've set up. I think that's probably the best way to proceed. And then we just need to publicise it, like you do with the link thread.

The advantage of the thread is that anybody can contribute to it. Even if you were to stop editing it, the replies could still be a place to add links. It's a bit robust.

Having our own actual wiki would be good too. Or making TDN open. That'd be pretty cool.

For the record, I enjoyed the safari. I only read through it cursorily while travelling, but I learned something. Would have been nice to link to some source files that were relevant, since I'm lazy and have no idea where to find them myself ;).

#2 If I had a dollar for every time I've found a nice software project only to discover that all the documentation was hosted on various team members sites who have long since stopped renewing their hosting...

I'd keep it somewhere central on a server/domain that isn't going anywhere if people stop paying the bills (e.g. google docs, skydrive, github)

#3

Quote:Having our own actual wiki would be good too

Problems solved ;-)

#4 Well I guess I wanted to start a discussion because I wanted to spark an initiative, i'm considering contacting wikidot about getting a free professional wiki there. @dB do you think the SC would back that initiative? I'm willing to port everything relevant from tdn to the new wiki, and start filing it up with content over the summer..
Just need ti get a green might and possibly some indikation from the community about whether this is something we want!

#5 Also, benefits from starting it on a 3rd party: everyone can edit pages, allowing for an iterative development of the wiki topics. They offer free advertisement for T3D! They i'll give us free professional support (assuming we quality ofc).

#6 One more thing to mention: we now have a CI job that generates the engine's doxygen documentation. This would be a great thing to leverage to increase the amount of documentation on the C++ side of the engine. The script auto-doc module is a great example of a well-documented module, amusingly enough. If more of our top-level modules had docs like that, I reckon we'd be much more confident in our ability to get people working on the source code.

We'll happily accept pull-requests that increase the documentation, though I imagine we'll have to do some vetting to make sure the writing is quality.

Also, having an externally hosted wiki does seem like a decent idea. What's the deal with free hosting on wikidot?

#7 Well basically they have this awesome "community wiki deals" where the wiki is getting the best possible deal, with unlimited space and great professional support etc, the catch (or in our case advantage) is that no one actually owns the wiki, it's owned and driven by a community with a group of admins, mods etc. It's a great deal really! And it has plenty of opportunities. We can choose to have little to none advertisements on the page iirc, and we can completely customize the wiki, we can even create a forum there if it's something we want in the future, and we can have the wiki on our own domain rather than a subdomain of wikidot.

#8 Great to see the C++ documentation CI job!

I spent most of last week trying to unify, massage and slightly reorganize the official Torque 3D and TorqueScript documentation as shipped with 3.5.1 into a more easily readable and editable format. I did it mostly for my own sake as an experiment, to be able to start thinking about how it could be improved upon:

torque-3d.readthedocs.org

It was a bit ironic that I first learned about the auto-doc feature when I started to read the reformatted scripting documentation, as I had simply converted the shipped CHM file wondering about how its source was generated in the first place... *sigh*

#9 That's the thing - the auto-doc module is "new" and the rest of the engine source needs to be updated with documentation....

During 3SS dev we started adding java-doc style comments to all of our script - mainly to leverage the pop-up help functionality in Torsion, but also just to help you out when you came back to refactor something later. When working on things in engine, adding that doc block isn't terribly hard and is a habit we all should try to develop - it helps everyone, even ourselves....

And there's another thread floating around the forums where I tried to explain how to use doxygen to generate T3D's engine docs - and Steve Acaster pointed out that doxygen is no longer included with the binary tools. And it seems that the build is expecting the log to be somewhere that it isn't, so that might still be a hiccup....

#10 I suspect it isn't going to be very helpful for people to generate the doxygen docs for themselves - we should just make the CI doc job more visible.

Anders - ooh. That's quite shiny. When it's done it looks like it'll be a great thing to point people to. There's a ton of good, if basic, info in that CHM manual.

That wikidot deal (link, for reference) sounds too good to last :P. If we can be confident that the provider won't go under or kick us off, then I think that's probably going to be our best shot.

I suspect though that a lot of the inertia this current site has is that people already have accounts, and there's a lot of into here :/. An adage I've heard from friends in business is that a new product needs to be ten times better to entice people to switch to it versus carrying on as usual... just to give some idea of the trouble we'll have getting any sort of mass migration to new forums. Though I doubt we'll have trouble getting people to jump onto something other than TDN.

#11 Yeah that looks awesome, shinyness always help new people keep their attention imo.

@dB, Well Wikidot has been around for a couple of years, so i dont think they are going under anytime soon :P
They have some elaborate explanation on why they can afford to make such a generous offer which you can read on their website. I'll contact them and see where it goes!

#12 I was about to suggest maybe we'll discuss it as a committee and then make an "official" (har har) request, but if you're keen, go ahead. It seems like it'll run independently of us anyway - you can't actually delete a community wiki, so apparently it'll live as long as their service does :P.

#13 I'm just eager to get started, but there is no rush because i've already reserved the "Torque3D" wiki, so I can work on that and we can always udgrade it when/if the SC gets ready.

An application wouldn't be the final part of the process anyways, it's just the first step so I reckon that the SC would have to be involved at some point in the process.

#14 Sweet. Let's make this happen!

#15 I think a functional forum search might qualify as "ten times better...."

#16 @dB some other things for the SC to consider, Wikidot can do more than just being a wiki. You can comment on the articles in the wiki, can also container forums or blogs, it could potentially be structured as a site that can fulfill the needs of the whole community. I'm not saying that it's the way to go, most of the current users prefer that everything stays the same and we just keep good ol' GG (i might even find myself in that crowd as well). It's just something that should go into considerations on what we will use wikidot for, and how to unify/seperate things.

#17 That's great. For now I don't think we'll need to bother with much more than the wiki, but it's really nice to know there are options there.

#18 Was thinking about updating the console reference part of my T3D documentation by generating it directly from the engines auto-doc dump.

Just a quick question. Are there any difference in output between dumping the docs in two stages using dumpConsoleFunctions() and dumpConsoleClasses(), with parameters set to only dump stuff defined in engine and not script, and just dumping with dumpEngineDocs()? Other than the first two writes the output to the console and the last one write to a file?

Here is an example of what I mean:

// Writes out all declared console functions to a file.
function writeOutFunctions()
{
   new ConsoleLogger(logger, "scriptFunctions.txt", false);
   dumpConsoleFunctions(false, true);
   logger.delete();
}

// Writes out declared console classes to a file.
function writeOutClasses()
{
   new ConsoleLogger(logger, "scriptClasses.txt", false);
   dumpConsoleClasses(false, true);
   logger.delete();
}

// Writes out the engine scripting documentation to a file.
function writeOutDocs()
{
	dumpEngineDocs("scriptEngineDocs.txt");
}

@Lukas: Is the wiki up somewhere and can be edited, even if it's not yet an community wiki? I would love to start organizing and sticking stuff into it as I scavenge the forums and resources for information. Not all topics fit to be put into the documentation and it would also be nice to use the wiki to write drafts (and expanded versions) of documentation articles.

#19 Ok, I have used both methods and generated two sets of documents with Doxygen. Now, I've only compared them by visually, but it looks like dumpConsoleFunctions()/dumpConsoleClasses() outputs everything, if the engine is a tool-build then also all tool-related console classes/functions will be documented, while dumpEngineDocs() output what has been the source for the CHM script reference file while and do not contain any tool-related documentation.

Are my observations correct?

#20 @Anders yup it's here, you are able to edit the wiki pages, but atm they are just displayed as a long list, I'm still working on the design.

To be able to edit, you have to get a WikiDot account and apply for membership of the site. I've been considering how open the access policy should be (maybe leaving out the "has to apply for membership" step) but for now I prefer to keep it a little closed. At least untill we know if we'll become a community site.