Documentation (...in being documentation)

[NLS]

Now don't take this wrong, I am just looking for answers AND OFFER HELP if needed.

Seems that WinUAE documentation is mostly a reiteration of the menu items without actually explaining anything (not for everything, but for many many things).

For example looking to improve my "semi-native" experience I am checking out display options...

So I went to the help file to look for what actually "resolution autoswitch" does, what the heck can "10%" for this setting may mean etc.
Or what "fields+" is etc.

In the docs for the above:
"Resolution autoswitch can be disabled, always on, 10%, 33% or 66%."
(eerm... ok?)
Line Mode (interlaced)
[...]
Double, frames or fields [+]
(yeah actually just mentions the setting)

These maybe known things for people spending time in EAB for years and seeing those options at their creation, but for the rest... no luck.

So, if Toni can help me understand what everything does, I am willing to clean up and update the docs.

In the meantime I would love some actual description of the above.

[andyhants]

Plus one for that. Spot on mate - couldn't agree more. I've been using WInUAE for over 10 years & don't understand a lot of the settings especially the display related stuff.

No-one is doubting Toni's fantastic commitment but some simple decent documentation is way way overdue.

[Foebane]

I'm sure Toni wouldn't mind someone else writing up the documentation for WinUAE, as long as he sees what is being written after having consulted him about the various settings, of course. Speaking as a programmer myself, I remember how fun it was to code programs in the first place, but not so much fun at all having to put aside the time to describe how to use them in a form that any layman can understand.

[project23]

Documentation is a huge task in the industry let alone in the opensource world.

With something like this it takes a writer (or various - different languages remember) who understands whats going on to take a lot of time out of their day to do the documentation.

The documenting writers should get as much credit for their tasks as do the code writers, again imo.

So if you or anyone familiar with UAE feel like giving up some time towards that goal, then seriously - good on ya.

Otherwise, it has to be the devs themselves, which takes away time from actual coding/development.

John

EDIT: forgot ya already volunteered! Good on ya, seriously... i'm sure there'll be no problem as the above posts have said.

[StingRay]

I guess there is no coder in this world who likes to write documentation. Coding is fun, writing about it isn't.

[Retro-Nerd]

There is the WinUAE help file. Though not 100% of all options are explained.


https://www.vware.at/winuaehelp/Welcome.html

[Toni Wilen]

It is better to contact winuahelp site maintainer.

Resolution autoswitch percentage: how big part of display needs to have lower resolution before switch (so that for example tiny hires part does not prevent switch to lores)

Interlace options should be quite obvious by simply testing what it does in interlaced mode Double = line doubling, interlaced becomes 25/30Hz progressive mode. Frames = 50Hz/60Hz alternate lines, Frames+ = 50Hz/60Hz alternate lines with opposite lines blanked (This looks more or less like real interlace).

[NLS]

thanks

[BippyM]

A wiki might be a good idea. Then others can update and maintain it

[malko]

Originally Posted by StingRay

I guess there is no coder in this world who likes to write documentation. Coding is fun, writing about it isn't.

Because everything we code "it's logical". And since it makes sense, there's no point in explaining it .

[shaf]

I agree 100% and having been a former Technical expert at a Software Development company now owned by S*P. I spent 90% of my time writing Technical Documentation explaining how things work.
Illustrations are important because it's easier to see what to change instead of writing about it for 4 paragraphs.
WinUAEHelp is good but it would be nice to also have a reference to when buttons and settings are moved to new panels.

[NLS]

OK...
(brief version at the bottom)

Let see:

1) By "winuahelp maintainer", you mean Georg Veichtlbauer and Peter Hutchison?

2) If yes I will contact them. But if you allow a brief harsh comment, since THERE ARE maintainers, I would expect documentation to be better than it is now... because it looks like there is no maintainer just quick additions by Toni himself or something - which is something that seems I am not the only one to believe. I mean should I repeat the example above?

So I went to the help file to look for what actually "resolution autoswitch" does, what the heck can "10%" for this setting may mean etc.
Or what "fields+" is etc.

In the docs for the above:
"Resolution autoswitch can be disabled, always on, 10%, 33% or 66%."
(eerm... ok?)
Line Mode (interlaced)
[...]
Double, frames or fields [+]
(yeah actually just mentions the setting)

This is not documentation. What should I tell the team about this? (No, really how should I phrase my email about this?) They don't already know? Because I already see the reply in my brain "well this is what we can do, if you think you can do better do it yourself" (which to be honest I might probably do if Toni is ok with it).

3) Wiki is INDEED a great idea. Toni what do you think?

4) (for the more general posts above)
I come from a coding background, although I have moved to different things (which I sometimes regret) -still in IT- and I disagree with comments like "coders don't do docs" (I used to do, I understand it is not easy or even feasible in big projects to be done by a single person though), or "it's logical so there is no point explaining" (I understand it is humorous... but tell me what "resolution autoswitch 33%" means if someone doesn't explain it to you).
Actually even for non "plain users", I still understand my 20y.o. code because of my commenting. So "explaining" is never a bad thing.
Documenting things for others that don't follow each step or even for yourself (nobody here is getting younger AFAIK), is not a bad thing.

---

To brief things up:
- I believe docs need major rework.
- Wiki is great for this job.
- I am willing to help and I believe if this turns to wiki, others will too.
- Documenting/commenting/explaining is A Good Thing (TM).

[Tomislav]

Originally Posted by Retro-Nerd

There is the WinUAE help file. Though not 100% of all options are explained.


https://www.vware.at/winuaehelp/Welcome.html

I see some errors in that help. I will list only 3 (there could be more, I didn't read whole help):
* In requirements it says "WinUAE 3.6: Windows 7 with SP1 or higher" - I'm running latest version of WinUAE on Windows XP.
* In Example Configurations it says that A500 is only OCS - It needs to be OCS/ECS - example: A500 rev 6a is ECS (If you write ranges for memory, write range for chip set, too)
* In same section for Floppies is written 880/1600 - correct would be 880/1760