Criterion for forking build instructions for new source versions(was: [sldev] Better build instructions)

[Rob Lanphier]

On 07/25/2008 02:58 PM, Boroondas Gupte wrote:
> Ricky schrieb:
>> the neext question is how do we know when to just tweak the existing 
>> article, and when to split a new article? Do we only ever split?
> Coming up with a criterion is easy. The difficult part will be to 
> apply it:
>
> My suggestion: Whenever it is possible to change the description so 
> it'll *keep working for the versions it used to apply to*, as well as 
> to one (or more) additional version(s), just modify the article (as 
> long as things stay practical and readable, that is). If that can't be 
> done in a reasonable way, fork the article.
>
> To determine when that's the case -- well, the wiki articles do have 
> discussion pages.

Another important consideration: consider inbound links, and keep the 
*links* up-to-date.  We need to consider that people will be deep 
linking to this wiki from unexpected places, and search engine results 
may not always be optimal.  For example, the page "Compiling the viewer 
(MSVS2003)" currently has no disclaimer in the title that it only 
applies to 1.20 and older.  When 1.21 is released (and maybe earlier), 
the ideal solution would be to fix that, and for the following:
1.  Rename "Compiling the viewer (MSVS2003)" to "Compiling the viewer 
(MSVS2003 - 1.20 and earlier)" with a new disclaimer added to the top
2.  A redirect from "Compiling the viewer (MSVS2003)" be placed to 
whatever article tells you how to compile the viewer using CMake, since 
someone who tries to visit that page title probably wants to build the 
latest viewer using MSVS2003.  Links to that URL should go to whatever 
the right instructions are for the latest viewer.
3.  Fix up any places where there's a link to "Compiling the viewer 
(MSVS2003)" and it really does mean "give me the old page".

If this sounds like a lot of work; well, it is, which is why fewer pages 
(in the future) is probably better.  It's handy to keep the old content 
around, but it should be increasingly difficult to find, because 
otherwise novices are going to stumble into it and get frustrated.

Rob