[Scummvm-devel] Documentation team (was: Bring testers to the team?)

[Max Horn]

Hi folks,

getting people to actively work on the docs again would indeed be  
nice. In the past, many people have volunteered for this, but few have  
actually done anything. I am not fully sure why that is (maybe because  
saying something is easier than doing it; maybe we also put the  
barrier to high; maybe something else).

Hence I am hesitant to talk about a "documentation team" or a "QA  
team" ... but that's just details on the nomenclature, so whatever... :)

Just go for it ;).



Am 13.07.2009 um 22:18 schrieb Thierry Crozat (Yahoo! Mail):

> Since sev will probably be the only one to read the rest of the mail,

Ha! I'll pretend I didn't hear that (only 29 mails more to go... on  
this list, I mean, not in total... *sigh*)

> I'd like to start with a question to the team: last time I updated  
> the screenshots on the wiki I noticed that the thumbnails are not  
> updated. This is for example visible on the following page
> http://wiki.scummvm.org/index.php/User_Manual/Running_and_Using_ScummVM#Adding_a_game
> The screenshots (when you click on the thumbnail) are from version  
> 0.13.0 but the thumbnails are from an older version (e.g. the Load  
> button is missing). The thumbnails are created automatically when  
> adding an image to the wiki, but apparently they are not updated  
> automatically.
>
> The only relevant info I found on google is that the line
> $wgHashedUploadDirectory = false;
> might be uncommented in LocalSettings.php , which means (among other  
> things) that the thumbnails are cached and that the cached  
> thumbnails need to be deleted in order for them to be updated. I  
> suppose there is no way for me to do this and only somebody with  
> access to the server on which the wiki resides can do it? Or does  
> somebody have more information on how to force an update of the  
> thumbnails on the wiki?

I will look into this. I was considering updating the Wiki from 1.13.3  
to 1.13.5 anyway. wgHashedUploadDirectory *is* false, but I'll first  
read up on it, I don't want to blindly toggle this setting.



>
>
> Now let's answer the mail from sev.
>
> Le 13 juil. 09 à 20:08, Eugene Sandulenko a écrit :
>
>> On Mon, 13 Jul 2009 18:52:52 +0100
>> "Thierry Crozat (Yahoo! Mail)" <thierry.crozat at yahoo.co.uk> wrote:
>>> Is it also time to try to revive the documentation team? I remember
>>> there was a discussion about it some time ago but it seems the idea
>>> (or the documentation team itself) died.
>> Actually this is the thing I wanted to discuss with you.
>>
>> Could you take the lead and become our documentation maintainer?
>
> Yes, I would be pleased to do it. The timing might not be perfect  
> though as I am going on holidays for ten days on Friday and I will  
> have no internet access (or intermittent access) which is not great  
> to work on the wiki and contact the other member of the team if  
> needed :-( (unless there is a way to work offline?).

The wiki cannot be used offline, but of course you can write texts  
offline and integrate them later on. Might be more work than it's  
worth, though :)

[...]

>>   - Review current documentation for omissions and complete it
>>   - Review for the readability, probably shuffle content around,
>>     split/merge pages
>
> Yes. Actually I wanted also to look at the wiki a bit more globally.  
> It makes no sense imho to have duplicate content in the manual /  
> platform / game pages. Therefore I wanted to have a look at this and  
> try to make a proposal on what content we should have in the manual,  
> in the platform pages and in the game pages (e.g. installation on a  
> specific platform, controls, compatibility, etc.). Then we can have  
> links between the different sections. Currently there seems to be no  
> rules and we don't have the same content on all the game pages or  
> all the platform pages.
>

Please do so; but note that we discussed this subject in the past  
here, too, so you might also wish to look at the -devel archives to  
find out about past opinions on Wiki reorgs. Some quick thoughts:
* duplicating data is not always bad. It has the drawback of tending  
to get out of sync, *but* it also can make it a lot easier for people  
to find stuff
* people cannot seem to agree where which particular information  
belongs. E.g. whether game X runs on platform Y: Should this be on the  
page for game X, or on the page for platform Y? Personally, I tend to  
think it belongs to both: If I want to know which games run on my  
platform, I look in the one place; if I want to know which platforms  
support a given game, I look in the other. Neither view can replace  
the other, IMO. Ideally, we'd store all this information in a  
database, and the game / platform pages would just be "views" of that  
database, and thus stay in sync...
Alas, with a plain Wiki, I don't think we can do that.



Cheers,
Max