github pages

[o11c]

I'm thinking about using github pages for internal TMWA documentation, because it allows fully generated HTML files from doxygen.

Currently, there's a dummy file at http://themanaworld.github.io/tmwa/

It is currently an error to access http://themanaworld.github.io/ because we don't have a dedicated repository for the root. Should I create one?

It might be more convenient to set a CNAME from doc.themanaworld.org before it gets serious content. On the other hand, it's not *that* critical to just access it on github.io, and if it's just for TMWA internals few enough people will be accessing it that the cost of changing it later wouldn't be too great.

Thoughts?

Note: I have NOT yet considered the consequences of how this will interact with the tentative plan for www.themanaworld.org being put on github pages. I intend this thread to be more about the intent, and less about the technical issues.

[Frost]

By "internal TMWA documentation," do you mean documentation about the server code? About content?

When I've faced a lack of documentation about something, the problem is rarely a lack of some special formatting language. There's usually a communication problem, and often an underlying lack of organization to record work.

I can't think why not to host documentation at github (as long as we have backups).
Would using doxygen (instead of, say, plaintext or wiki or HTML) improve the chance that things will get written down?

[wushin]

He was planning on oxygen and some of melkior's stuff I believe.

[o11c]

By "internal TMWA documentation," do you mean documentation about the server code? About content?

About server code.

When I've faced a lack of documentation about something, the problem is rarely a lack of some special formatting language. There's usually a communication problem, and often an underlying lack of organization to record work.

This is orthogonal to the kind of documentation you've been lacking. Current documentation methods are unsuitable because doxygen goes straight from source code into .html, and does not support any markup formats.

I can't think why not to host documentation at github (as long as we have backups).

The information is stored in git, so anyone who clones the server will have a copy.

Would using doxygen (instead of, say, plaintext or wiki or HTML) improve the chance that things will get written down?

Doxygen is HTML, generated from the source code. Due to the lack of meaningful comments, it is mostly useful for the control-flow graphs right now, but that will improve and help me not go totally insane.

In the long term, I *might* move a couple of wiki pages over.