Thread Rating:
  • 0 Vote(s) - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Refactoring the Wiki
09-29-2011, 03:53 PM,
Refactoring the Wiki
Hello everyone!

I am writing a new readme and came across that the wiki some what oddly structured. The readme classically is one thread from presentation, over downloading, compiling and installing to running VDrift. Each of these steps is instantiated for the four supported operating systems and links as a whole to the wiki for more detailed information and alternatives.

On the wiki however were articles for each step and operating system, thus separating in an orthogonal direction to the thread of the readme. As a result there were 4 articles on compiling with overlapping instructions on prerequisites. As the articles linked in the readme were containing links to the operating system specific articles only, I brought their content together in the respective master article.

I hope this helps consolidating and extending as intended. It would be great, if someone could review my changes and/or discuss them here.

09-29-2011, 05:27 PM,
We originally had all operating systems etc. on the same page, but decided that the pages were getting too long and hard to read, especially for non technical readers, so we started to split them up. Maybe we didn't do it in the best way possible, but I'm not sure putting everything back on one page is the best way forward.
10-01-2011, 09:57 AM,
Hello Timo6!

I am sorry to hear that I am doing double work. I can not find any rationale on the wiki or this forum on why the split was made. I think though, that the wiki should not be the first place for none technical users, anyway. They should be able to install via precompiled packages or compile for themselves reading only the readme distributed with the source code.

Nonetheless I agree that the wiki should be improved and I am trying to use my work with the readme and installation testing as a guidance for overhauling the wiki. Excuse me if I cause some disturbances on the way. Maybe it will be the best to split some articles again after I am done for this time, but I think at least now, having the readme and the wiki structured alike facilitates mutually improving them the most.

The longest page is currently /Compiling. I think that much of its content can be consolidated at more appropriate locations. My strategy would now be to source out the paragraphs on prerequisites and installing, since they are massively overlapping with /Software_requirements and /Installing.

In my mind, the train of thought should be something like this:

- hardware requirements
- software requirements
- getting VDrift
- getting build dependencies
- compiling
- installing

In each of the article preceding and following in this train of thought should be named in the introduction to guide the user through the process.

I agree that orientation might be hard for non-technical users, because they might not even know ho to use their operating system in the way the wiki suggests. Therefore I think, naming them more often could affirm users unfamiliar with the wiki's structure to be on the right article and or paragraph respectively.

Forum Jump:

Users browsing this thread: 1 Guest(s)