Drop dev wiki?

[piotrdz]

I would like to propose that we remove the old wiki for developers. Information contained there is in almost all cases outdated and sometimes even no longer relevant. Besides, I guess there are very few visitors from outside our project and in our project we don't need to visit this site at all. I myself can't remember the last time I visited there.

What I propose instead, is to post the relevant and updated parts of wiki as sticky posts in this forum. This way, all discussions and information will be gathered here in one place, and besides, it may make this forum feel more alive.

What do you think about this idea?

[tomangelo]

Good idea, but how it will be organised? Multiple sticked threads, or one sticked post with hyperlinks to another, non-sticked threads?

[RaptorParkowsky]

I agree, but I think all official development informations should be in repositories, READMEs and GOLD GDD. Forum should be only for discussions and announcements about changes in the game, new features etc.

[tomangelo]

@RaptorParkowsky : But how would you store all these informations about compiling under different compilators and OS'es, about working with 3D models, 2D graphics, code styling and many more in READMEs? It's so much informations, that would be quite difficult to store in repo text files.

[RaptorParkowsky]

@tomangelo : Well, for me It's obvious that these kind of informations should be stored in obvious and up-to-date place for programmers/contributors or other interested people. GitHub is that place, forum is for discussions about everything in non-official form. Nobody will searching infos about compiling GOLD on some exotic platform on forum, where one important information can be often camouflaged by textwall.

We can do even more "readme" files just for some kind of informations, if we want to keep the main README.md or CONTRIBUTING.md files in clarity.

[tomangelo]

But how many "readme" files will we have then? 10? Or even more?

[Simbax]

Maybe we will just link to forum subcategory in READMEs and CONTRIBUTING?

[krzys_h]

I believe it would be better to have dev information on GitHub. If we don't want to have multiple documentation files (why not?), GitHub also has an integrated wiki system (it's disabled right now)

[Simbax]

+1 for GitHub Wiki

[RaptorParkowsky]

But how many "readme" files will we have then? 10? Or even more?

This is still text files, no binary PDFs with integrated fonts, images etc. so it does not matter how much of them there will be in repository. The only problem is to keeping them up-to-date and writing them as clear as it possible that everyone could understand them.

Our game isn't the Linux kernel or anything very complicated so probably we don't need so much to document about compilation, contribution and translating. Of course the project will growing up, but not that much that we would need a whole wiki with thousand pages about every single detail.

Maybe we will just link to forum subcategory in READMEs and CONTRIBUTING?

You will be keeping files on repo up-to-date?
or
You will be keeping files on repo && posts on forum up-to-date?

Again, the forum is a good place for discussions and setting the rules of ICC (good example of topic about rules: http://colobot.info/forum/showthread.php...03#pid5903), but not for documentation.

GitHub also has an integrated wiki system (it's disabled right now)

If we will need that, so I'm ok with enable this feature.

[tomangelo]

This is still text files, no binary PDFs with integrated fonts, images etc. so it does not matter how much of them there will be in repository. The only problem is to keeping them up-to-date and writing them as clear as it possible that everyone could understand them.

Our game isn't the Linux kernel or anything very complicated so probably we don't need so much to document about compilation, contribution and translating. Of course the project will growing up, but not that much that we would need a whole wiki with thousand pages about every single detail.

Compiling under Linux, under Windows, under MacOS, maybe under another OSes with different compilators.
Working with 3D models, creating, importing, exporting, documentation of our model format.
Working with textures, with sound, code styling and many, many more informations.
I'm not sure if storing all these informations in plain text files will be best idea. Storing on GitHub wiki or in some forum would allow us to creating more readable content, plain text wall might be scary for new users, but formatting that text and adding some graphics would make it more user-friendly.

[krzys_h]

GitHub wikis support Markdown, the same format that is used in all our README files.

[Simbax]

You will be keeping files on repo up-to-date?
or
You will be keeping files on repo && posts on forum up-to-date?

What does it have to do with my proposition? O_o

If you suggest that we will not keep the documentation we are talking about up-to-date then it does not depend on the subject at all, it only depends on TerranovaTeam. Doesn't matter if the documentation is on GitHub, in-game or wherever.

Again, the forum is a good place for discussions and setting the rules of ICC (good example of topic about rules: http://colobot.info/forum/showthread.php...03#pid5903), but not for documentation.

Why not? I'd consider it actually a better place because of marking threads as unread after editing. We have so many commits a day and so much spam at IRC that there is a high probability of missing the update of the documentation.

Nobody will searching infos about compiling GOLD on some exotic platform on forum, where one important information can be often camouflaged by textwall.

That's surprising, because when I'm searching for something I firstly check a wiki and forums. Honestly, most of the time there is little, if any, useful information in all these README files. But maybe that's just me.

Also, we already have so many READMEs in many different folders, that it's confusing. Sticky threads on forum or properly maintained wiki are way better in my opinion. And they're much easier to modify, as one do not need to use git and no one will be afraid of fixing some typos or minor updates because of "nah, I'll fix it when there will be something important to update". Also I don't think that spamming with commits "Update documentation" on the main game repository is a good idea.

So my vote goes for forum or GitHub wiki, does not make much difference for me. I'm definitely against keeping ALL documentation in the repository. It's not a place for that, it's for the source code.

[krzys_h]

And they're much easier to modify, as one do not need to use git and no one will be afraid of fixing some typos or minor updates because of "nah, I'll fix it when there will be something important to update".

Keep in mind that GitHub wiki is essentialy a git repo - but still, you can do everything in the web interface (I'm only not sure about uploading images, that may be possible only by pushing to the wiki repo directly)

EDIT: I just enabled it, I'm pretty sure only @piotrdz and I have permissions to do this - https://github.com/colobot/colobot/wiki
EDIT2: And I also removed old history that was there just so we can start fresh

[RaptorParkowsky]

What does it have to do with my proposition? O_o

Because linking in main README.md and CONTRIBUTING.md to forum is fragmentation of informations. You will need to keep up-to-date those informations in two places at once. And it will be hard to keep those infos in coherent form.

Why not? I'd consider it actually a better place because of marking threads as unread after editing. We have so many commits a day and so much spam at IRC that there is a high probability of missing the update of the documentation.

Again and again I say that the forum is only for discussions, not official documenting. We can organize and discuss things here, but the main and official informations should be in place DESIGNED for such kind of informations.

That's surprising, because when I'm searching for something I firstly check a wiki and forums. Honestly, most of the time there is little, if any, useful information in all these README files. But maybe that's just me.

Most of the people have no time to searching infos about technical aspects of the game in such places like forum. They prefer wiki or GitHub, because forum is for discussions and there's usually a mess of blended and (non)important informations. It's hard to writing and discussing on forum and keep that discussions clean.

Also, we already have so many READMEs in many different folders, that it's confusing. Sticky threads on forum or properly maintained wiki are way better in my opinion. And they're much easier to modify, as one do not need to use git and no one will be afraid of fixing some typos or minor updates because of "nah, I'll fix it when there will be something important to update". Also I don't think that spamming with commits "Update documentation" on the main game repository is a good idea.

Why not different READMEs? Every README can be about different technical aspect of the game. When someone will want to contribute in, for example, translations, then he just read TRANSLATING.md and focus on main thing that he need to do and content that he need to provide to us or commit/request himself. The same situation will be when we decide to use GitHub's Wiki. He just go into right page.

[tomangelo]

Because linking in main README.md and CONTRIBUTING.md to forum is fragmentation of informations. You will need to keep up-to-date those informations in two places at once. And it will be hard to keep those infos in coherent form.

Wait, as far as I understand, there will be informations in forum and links in GitHub. How many times will you change the links?

Again and again I say that the forum is only for discussions, not official documenting. We can organize and discuss things here, but the main and official informations should be in place DESIGNED for such kind of informations.

GitHub is designed to keep source code of the project. I've never seen a repo with tons of Readme, there was just such infos like "how to compile and install", that's all, all of such infos like working with models was described on wiki or on forum.

Most of the people have no time to searching infos about technical aspects of the game in such places like forum. They prefer wiki or GitHub, because forum is for discussions and there's usually a mess of blended and (non)important informations. It's hard to writing and discussing on forum and keep that discussions clean.

There is such thing like sticking posts. We can stick one thread with up-to-date list of important threads, with hyperlinks to them.

Why not different READMEs? Every README can be about different technical aspect of the game. When someone will want to contribute in, for example, translations, then he just read TRANSLATING.md and focus on main thing that he need to do and content that he need to provide to us or commit/request himself. The same situation will be when we decide to use GitHub's Wiki. He just go into right page.

Why not different threads on forum? Every thread can be about different technical aspect of the game. When someone will want to contribute in translations, then he just read a thread about translations, with divided descriptions about creating new languages, editing existing one in separate posts, and so on.

[Simbax]

Because linking in main README.md and CONTRIBUTING.md to forum is fragmentation of informations. You will need to keep up-to-date those informations in two places at once. And it will be hard to keep those infos in coherent form.

Ok, ok, here's a link I am talking about: http://colobot.info/forum/forumdisplay.php?fid=62
Or that one: http://colobot.info/forum/forumdisplay.php?fid=63
Or, while we're at it, that one: http://colobot.info/forum/forumdisplay.php?fid=64

[irony]Yeah, giving links in one README file is such a hard to keep up-to-date information! Links keep changing every 5 seconds, right?[/irony]

Again and again I say that the forum is only for discussions, not official documenting. We can organize and discuss things here, but the main and official informations should be in place DESIGNED for such kind of informations.

Again and again, give us one reason why forum can't be a place for the main and official informations. Because I have a lot of reasons why it can, but I don't see a point of giving links to forums that act like that (even better than some portals and wikis!), if you keep saying some biased opinions without any reasoning behind it. Give us something to discuss, not only opinions.

Most of the people have no time to searching infos about technical aspects of the game in such places like forum. They prefer wiki or GitHub, because forum is for discussions and there's usually a mess of blended and (non)important informations. It's hard to writing and discussing on forum and keep that discussions clean.

Oh, really? Have you made a statistical research about that? No? Your argument is invalid then. No, a group of friends is not a statistical group. If you are telling from your own experience then please, DO NOT USE TERM "MOST PEOPLE", unless you are some sort of god.

Also it was often (and I am talking about all projects in general, to make it clear) a lot easier to just read some __STICKY__ threads to clear basically 90% of doubts than, what you called it, "searching" through billions READMEs scattered everywhere or trying to find an information on portal or empty wiki. People can also post under these threads, for example to remind about a need of update, giving additional informations, asking and answering new questions etc. That's a huge advantage.

Why not different READMEs? Every README can be about different technical aspect of the game. When someone will want to contribute in, for example, translations, then he just read TRANSLATING.md and focus on main thing that he need to do and content that he need to provide to us or commit/request himself. The same situation will be when we decide to use GitHub's Wiki. He just go into right page.

Yeah, "the same situation will be when we decide to use" forums. "He just go into right" thread.

Also, tell me more about these super READMEs that even you can't read and I'm wondering if you even know that half of them exist, because not so long time ago you were complaining about how to edit translations and I'm still not sure that you understood them, even I have understood them after trying to explain them to you. The only thing you needed to do was to search something about gettext format and read some tutorials. Situations like this are demotivating, because it is clear that there will always be lazy people who will not even try to find ANY information before asking, so what's the point of ANY documentation if they will be complaining and asking anyway.

What I want to say by the above paragraph is that you are a person that can't use current documentations and at the same time you are defending it. I am at least using it and I am only telling what is comfortable for me in that matter. Tons of READMEs are definitely not.

Also, read what @tomangelo 's said above.

EDIT: Oh, and also, I think the discussion here is over, because @krzys_h 's has already set on GitHub wiki and if you haven't noticed I have already rewritten one thread to a proper wiki page and I'm pretty sure that most of TerranovaTeam will not even look there more than twice, not even mentioning editing it. I hate that a lot of times here people who shout the loudest have nothing to do with a case. I could swear that one day I will be giving warns for empty discussions for people who are not doing anything related to the subject. Yes, I know, I would get this kind of warn too, doesn't change my point.

[piotrdz]

Oh, what a discussion. I just wanted to simplify things, and gather them in one place and now we have begun a flamewar about what's better

I think that an ideal solution to this problem would be to put the information we want visible in the place where people are most likely to look for it. Forgive me for saying so, but the old dev wiki was not such a place.

Now, our forum is one such place, and our "space" on Github is another such place. And these are the only choices that come to my mind.

Now, I can understand the position that our forum should be for discussions, and not keeping documentation. Ok, fine, so we use Github in some way.

As far as Github wiki is concerned, I'm not too sure it is a good choice. For one thing, I've tried once it and it's pretty limited in its functionality. And for another thing, it's Yet Another Wiki, which is to say, a still different place, which needs our attention and occasional maintenance. And I wanted to avoid that.

So keeping this all in mind, I would propose to put our documentation in our repository. And as to the objection that there are technical "difficulties" of putting everything in README files - it is a false assumption. Other projects do use their repository as main source of documentation, and in fact it can be done very elegantly.

To give you one example, repository of project clang-tools-extra to which I intend to contribute some code, has this directory in its repository: https://github.com/llvm-mirror/clang-too...aster/docs. You can see there a number of *.rst files, which are documentation written in something similar to markdown: https://en.wikipedia.org/wiki/ReStructuredText. From these files, an automated script can generate nice HTML files: http://clang.llvm.org/extra/.

We could introduce a similar system here - put documentation in *.rst files in repository, and update them regularly with each release. And we can set up our CI server to generate documentation with each build, keeping it always current, and uploading it to any location we want on our server. And all this has an added bonus of being visible to every person who downloads the repository. They do not have to go looking for documentation, if they already have it on their disk.

[Simbax]

That's a nice and constructive post here @piotrdz .

If these files will be well and clearly organised I will not fight against it. I hope there will be really only one place for such a documentation and it won't be mixed with the source files too much. I'd personally prefer forums anyway though, but this doesn't really matter, what matters is that important informations should be easy to find, easy to read and kept up-to-date. The last one is the biggest problem considering how it was before with Colobot and no matter how well and in what way we'll write this documentation, it'll be dead after a while as the others were if we won't be maintaining it properly. So during choosing the way we'll keep it we should also think about our comfort of editing it.

[piotrdz]

Also, please consider that our wiki for users does not have to be updated that often, as we currently are not making many changes to the gameplay or CBOT.
But the information stored in dev wiki may get outdated very easily, with even one commit to repository, because we describe there the internals of our game engine, file formats, etc. So we should take special care to keep it up to date. This is why I propose to keep it somewhere along with our source files, so that one commit may update code and all relevant documentation as well.