project-navigation
Personal tools

Author Topic: A Wiki for Each Manual  (Read 5622 times)

Offline TC

  • Rookie
  • ***
  • Posts: 23
    • View Profile
A Wiki for Each Manual
« on: August 04, 2010, 09:27:49 pm »
This website is well organized. It was a good idea to build the manual, the FAQ, and other parts of the website in a wiki. However, I propose that instead of a single wiki, the website would be better served by multiple wikis. Specifically, I suggest one wiki for administration and development and three wikis for the game manuals 2.2, 2.3, and 2.4.

Organizing the documentation by version is a cleaner approach than organizing it by topic and addressing version differences on each page. If that argument isn't persuasive, consider that documentation is subject to the same revision control issues as source code, and it just makes sense to create a branch for each version.

MediaWiki has the capability to host multiple wikis with a single user base. If the website administrator would like to pursue my multiple-wiki suggestion and wants help with the MediaWiki configuration, just let me know.

-TC

Offline bayo

  • Professional loser
  • Project Coder
  • Captain
  • ***
  • Posts: 733
    • View Profile
Re: A Wiki for Each Manual
« Reply #1 on: August 05, 2010, 12:36:33 am »
Hello.

It is useless and overcomplex. MediaWiki also support subpages and namespaces.

Plus it will create problem to follow editions.

But you are right, we should move some content as u say, but especially game translation, i think.

Offline Duke

  • Administrator
  • PHALANX veteran
  • *****
  • Posts: 1037
    • View Profile
Re: A Wiki for Each Manual
« Reply #2 on: August 05, 2010, 12:54:45 am »
... and three wikis for the game manuals 2.2, 2.3, and 2.4.
I agree with bayo.
2.2 is obsolete. Few users will want to use 2.2 once 2.3 is out.
2.4 manual is ...  uhm... not really written yet.

Offline TC

  • Rookie
  • ***
  • Posts: 23
    • View Profile
Re: A Wiki for Each Manual
« Reply #3 on: August 05, 2010, 01:45:50 am »
Bayo and Duke,

From your comments, I can't tell whether or not you see my point.

The 2.4 manual hasn't been written yet, but what happens the first time someone wants to document something in 2.4 which is different from 2.3? Do you end up with one wiki page which is ambiguous regarding its applicability; do you end up with one wiki page with a 2.3 section and a 2.4 section; or do you end up with two wiki pages? Having two wiki pages seems like the best structure to me.

-TC

Offline bayo

  • Professional loser
  • Project Coder
  • Captain
  • ***
  • Posts: 733
    • View Profile
Re: A Wiki for Each Manual
« Reply #4 on: August 05, 2010, 11:05:55 am »
Yes, 2 wiki pages is a good choice. For example:

Manual 2.3
Manual 2.3/A sub page
Manual 2.3/Another sub page
...

Manual 2.4
Manual 2.4/A sub page
Manual 2.4/Another sub page
...

Wikibooks works like that without too much problems.

Anyway i dont know the current manual content. And what is about 2.2, 2.3 or 2.4. Maybe the manual page (http://ufoai.ninex.info/wiki/index.php/Manual) is not up to date.

Offline Duke

  • Administrator
  • PHALANX veteran
  • *****
  • Posts: 1037
    • View Profile
Re: A Wiki for Each Manual
« Reply #5 on: August 06, 2010, 12:05:20 am »
Do you end up with one wiki page which is ambiguous regarding its applicability;
do you end up with one wiki page with a 2.3 section and a 2.4 section; or
do you end up with two wiki pages?
Having two wiki pages seems like the best structure to me.
Of course we don't want #1 ;)
My personal favorite would be a mix of #2 and #3. Sections per version when less than some 20% of the page are different; separate pages if things are almost completely different.

Having two separate manuals is surely a 'clean' solution, but seems to be overkill to me because:
- an unknown percentage (66% ?) of the manual did not change at all
- in those cases where we apply changes to both 2.3 and 2.4 (bugfixes) it can become a maintenance nightmare.

Offline bayo

  • Professional loser
  • Project Coder
  • Captain
  • ***
  • Posts: 733
    • View Profile
Re: A Wiki for Each Manual
« Reply #6 on: August 06, 2010, 02:04:33 pm »
Quote
it can become a maintenance nightmare
Not so sure, cause, manual for stable version should not change at all. Only dev version need update (while it is not stable). But that's right, it need work.

Offline TC

  • Rookie
  • ***
  • Posts: 23
    • View Profile
Re: A Wiki for Each Manual
« Reply #7 on: August 06, 2010, 06:02:13 pm »
Let's put this discussion into action. I just created this page: http://ufoai.ninex.info/wiki/index.php/Manual/Troubleshooting . It is ambiguous regarding its applicability to different versions of UFO AI. How would you suggest I fix that?

-TC

Offline bayo

  • Professional loser
  • Project Coder
  • Captain
  • ***
  • Posts: 733
    • View Profile
Re: A Wiki for Each Manual
« Reply #8 on: August 06, 2010, 08:09:15 pm »
The "Manual" page can provide entries for differente troubleshooting page per version. Here it is a good idea to split pages i think.

Offline TC

  • Rookie
  • ***
  • Posts: 23
    • View Profile
Re: A Wiki for Each Manual
« Reply #9 on: August 06, 2010, 10:27:54 pm »
Would it be appropriate, then, for me to move Manual/Troubleshooting to Manual/2.3/Troubleshooting?

-TC

Offline NicAdi

  • Rookie
  • ***
  • Posts: 23
    • View Profile
Re: A Wiki for Each Manual
« Reply #10 on: August 07, 2010, 12:04:54 am »
Would it be appropriate, then, for me to move Manual/Troubleshooting to Manual/2.3/Troubleshooting?
I'd rather go for something like "Manual » Troubleshooting » v2.3". It simply makes more sense to me, at a first glance, to have the version number as the subcategory to the troubleshooting topic. Besides, it is conceivable there will be quite a bit of superposition to older versions; grouping them together more tightly may prove quite advantageous...
« Last Edit: October 16, 2010, 03:40:50 pm by NicAdi »

Offline bayo

  • Professional loser
  • Project Coder
  • Captain
  • ***
  • Posts: 733
    • View Profile
Re: A Wiki for Each Manual
« Reply #11 on: August 07, 2010, 12:48:30 pm »
Something more like that, yes, as you done for the "Improvment" page.