Possibility of an official "Documentation Team"?

[glokidd]

Hi all, GloKidd here

For a long time now there has been a dedicated group of users that maintain and provide documentation in the forms of wiki editing, Random listing, guides, etc. Most of these users, myself included, dedicate their time in hopes of proving themselves a valuble asset to the ScummVM team (ive been trying to earn a spot for months ) but for the most part we are just glad to contribute.

Heres my Idea...

How about creating a "Documentation Team" or "Doc's Contributor" User group here at the forums? Anyone who has made contributions to docs whether in the form of wiki editing, patch submissions, or guides would then be made a member. I think there are many members of these forums that would like to have a more active role in ScummVM and creating such a user group could be just what they need to get motivated and contribute. Who knows, perhaps it would cause a boom of activity in the documentation area, motivating new people to take part and try to earn their way into the group

There are ready more than a handfull of users here that would easily fall into such a group: SirDave, md5, Clem, myself, metafox, clone2727, JoachimEberhard, and many, many more

I think this would ba a good way to give recognition to those who have spent way to much time punching away at text boxes in hope to add their own little something to our favorite program.

I dont know, its just an idea, what do you guys think?

[sev]

I think it is a good idea. Also anyone of you if you want to work on our documentation, welcome to the project Team.


Eugene

[glokidd]

Very cool Im glad that you think this is a good idea sev

I look forward to the possibility of an official documentation team forming soon.

Most membergroups have a group moderator, I am more than willing to volunteer for this (i have some recent experience as a forum admin) but there are probably some others far more qualified for such a role. clone2727 or JoachimEberhard come to mind off hand as they are already ScummVM team members (most likely the former as Joachim seems to have been pretty busy with RL stuff for the last while)

I am also eager to hear what some of the potential members have to say about this possibility

All that being said i think im going to be smiling all day

P.S. It would seem that the plan is already working
*wrings hands and laughs maniacally a'la Dr. Fred*

[fingolfin]

Hm, in my eyes a "documentation team" group as such is mostly a way to give people a "honorific" title. It by itself won't give us any documentation by some magical means... But if it helps to motivate people a bit, why not.

Anyway, I am grateful for all and every contributor to the ScummVM documentation. Thanks!

However, with maybe the exception of sirdave's work, there is in general a certain lack of coordination and vision. Lots of small bits and pieces get added here and there, but the big chunks, like a user's manual, are not touched even with a long pole. That's a pity , although understandable.

So, while it's certainly fun to make Wiki pages on each and every game ScummVM supports, I think that those are (in their current form) not that important -- as they mostly do not contain much useful information. Anyway, I just started a separate "Documentation TODO" page on the Wiki, listing some ideas and proposals, and I hope that some get be picked up by people, or that people add own ideas to that list. See http://wiki.scummvm.org/index.php/Documentation/TODO .

Finally, since so far every single person who promised to work on a User's manual failed to deliever anything at all (even if I tell them that they can write it in whatever format they prefer), I think we need to reconsider this sore spot, too. We should consider starting a "User's manual" section on the Wiki. I am very curious to see if *anybody* will contribute something there...

[md5]

We should consider starting a "User's manual" section on the Wiki. I am very curious to see if *anybody* will contribute something there...

It can always be created as a page containing the contents of the README as a start, and then let people with wiki access work on it

[fingolfin]

I think I'd prefer if it was created as a page with only the proposed outline as content, and maybe the existing text from the DocBook manual project.

Because a lot of what is in the README badly needs to be revised, and I believe it's better to only selectively copy those parts of the README which are good, as opposed to trying to modify the existing content. Else, it's surprising how many years totally bad and bogus sections can survive, as I discovered recently...

[clem]

There are ready more than a handfull of users here that would easily fall into such a group: SirDave, md5, Clem, myself, metafox, clone2727, JoachimEberhard, and many, many more

thanks, but I'd rather have the honorific title of "resident forum troll"

[clone2727]

Well, I've been pretty busy recently (and just lazy before then), but I'll be getting to that documentation... eventually

[glokidd]

@fingolfin
just for clarification, did you want the current contents of manual.xml transfered to the documentation TODO page you created or to a new page to keep the layout proposal clean? This is probably somthing i can see myself sinking my teeth into, if theres one thing im good at its copy/pasting

I also really like the idea you mention about doing a major expansion of the game data pages. This is another one of those things where a wealth of examples are already present all over the wiki, so im a bit more confident than usual that i will be able to figure out how to go about making contributions

I also agree completely that creating a Doc's team group won't just suddenly make the manual a reality.
From the first day i started interacting with the team, even at the forum level (asking the manditory silly noob questions ), i knew that this was a project that i wanted to one day be a part of. Over time i saw more and more of my friends in the scene earning spots on the team and progressing in their coding ability.This was the motivation i needed to start seriously looking into how i can contribute. I spent several days searching through the TODO pages on the wiki, mentally checking off or making note of what entries my current skills allowed me to try to help out with. Unforutunately my C++ learning stalled (largely due to my not understanding the basics of the code and attemping to figure it out using something as large and complex as ScummVM for my first exapmle)and i became very discouraged that i would ever be able to reach my goal. Then i noticed that port specific documentaion had been asked for on the TODO page and i thought "hey! i might actually be able to do that " I then started compiling everything i had learned about running ScummVM on PalmOS into a usable ReadMe/FAQ.

Oops, that got a wee bit too autobiograpical, sorry about that My point in saying all this is that it was the want and need to contribute and earn a spot on the team that inspired me to start making such a document. Im hoping with this new doc's usergroup to provoke that same "I gotta attain this" feeling in others

[fingolfin]

Oh great documentationt team, anybody interested in syncing http://wiki.scummvm.org/index.php/PlayStation_Portable and http://forums.scummvm.org/viewtopic.php?t=3466 ?

@glokidd: Ideally I still would prefer a DocBook manual over one in the Wiki, because with Docbook I can create both a HTML multi page version, a HTML single page version and a PDF, to be included in the website and in the ScummVM download, and if you want you can even print it -- with the Wiki version, I have no idea how one would make a single downloadable version out of it.

Yet, as it seems it is impossible to find anybody to work on the DocBook version, I believe it's still better to have a great Wiki manual than to have nothing. In fact I could, if I wanted to, convert Wiki text back to DocBook (with lots of sweat and blood, though, but in the end it's straight forward work).

As it is, the new manual would start on a *new* page, the page I made is just a TODO page with a TOC proposal, after all. feel free to have a start at it.


@all: Well, my suggestions on how to improve the Wiki, in particular the game pages, still holds. Wonder if anybody is interested in getting this working? If you are clever you can simply copy and paste lots of data which already exists in other places, and add placeholders to the templates etc. -- so it should be possible to get this started at least, if one is dedicated enough .

[Espiox]

I'd love to be able to help out with the Wiki or Documentation etc if you guys need the help.

[clone2727]

I'll be getting on the DocBook asap, but I've been awfully busy in recent weeks.

[sev]

I'd love to be able to help out with the Wiki or Documentation etc if you guys need the help.

Please, subscribe to scummvm-devel and give us a bit of introduction of yourself and also tell your plans on what would you like to work on.


Eugene

[MetaFox]

I'll work on a big chuck of Documentation/TODO today.

Hopefully I'll be able to get all of the wiki game pages added with the relevant information today - if not, then tomorrow (not including the AGI fan game pages though - they still need some major work - I'll get to them eventually too though).

I'm also taking a look over the manual both in the docbook directory in the subversion tree and in the wiki. If I update the wiki, I'll update the docbook (and submit a diff to the patch tracker) as well.

[Gucek001]

Are there any tools to easily 'backport' bunch of HTML files to DocBook? I'm asking, because I started to convert (with some little editing) SirDave's manual to CHM format. I'm definitelly not ready to create it properly in DocBook from scratch... (Unless there are some good Windows tools I didn't discover yet).
Unfortunatelly my main/system 250GB HDD just died and it will take about 2-4 weeks to make everything usable again and to resume my work...