Thread Rating:
  • 0 Vote(s) - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Drop dev wiki?
#18
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 Undecided

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.


Messages In This Thread
Drop dev wiki? - by piotrdz - 08-28-2015, 05:34 PM
RE: Drop dev wiki? - by tomangelo - 08-28-2015, 05:58 PM
RE: Drop dev wiki? - by RaptorParkowsky - 08-28-2015, 06:14 PM
RE: Drop dev wiki? - by tomangelo - 08-28-2015, 09:09 PM
RE: Drop dev wiki? - by RaptorParkowsky - 08-28-2015, 09:29 PM
RE: Drop dev wiki? - by tomangelo - 08-29-2015, 12:00 AM
RE: Drop dev wiki? - by Simbax - 08-29-2015, 06:13 AM
RE: Drop dev wiki? - by krzys_h - 08-29-2015, 09:25 AM
RE: Drop dev wiki? - by Simbax - 08-29-2015, 11:25 AM
RE: Drop dev wiki? - by RaptorParkowsky - 08-29-2015, 11:41 AM
RE: Drop dev wiki? - by tomangelo - 08-29-2015, 01:25 PM
RE: Drop dev wiki? - by krzys_h - 08-29-2015, 02:26 PM
RE: Drop dev wiki? - by Simbax - 08-29-2015, 05:21 PM
RE: Drop dev wiki? - by krzys_h - 08-29-2015, 07:23 PM
RE: Drop dev wiki? - by RaptorParkowsky - 08-30-2015, 12:28 PM
RE: Drop dev wiki? - by tomangelo - 08-30-2015, 12:51 PM
RE: Drop dev wiki? - by Simbax - 08-30-2015, 03:41 PM
RE: Drop dev wiki? - by piotrdz - 08-30-2015, 06:49 PM
RE: Drop dev wiki? - by Simbax - 08-30-2015, 07:27 PM
RE: Drop dev wiki? - by piotrdz - 08-30-2015, 10:08 PM
RE: Drop dev wiki? - by tomangelo - 08-30-2015, 10:38 PM
RE: Drop dev wiki? - by Simbax - 11-24-2015, 04:31 PM

Forum Jump:


Users browsing this thread: 2 Guest(s)