RemoteTech
RemoteTech copied to clipboard
RemoteTechnologiesGroup
In-Game Documentation
I'm surprised this isn't a standard. But all these wikis floating about... Bollocks I say. If you're in KSP, you don't want to have to leave the game or minimize it or tab out to go hunt for it on a wiki.
I suggest adding verbose and well-written in-game documentation for the mod. Much like what FAR does. Some of the constant repeat explanations in the forum thread are the same tired questions.
I'll even volunteer to write the documentation myself provided I'm given a working list of points organized for writing and an indication of where they'll show up. I'm good at explaining things in clear detail once I've had a few draft runs on it.
I'd be willing to contribute to this, as well (either generating documentation or reviewing/providing feedback). To expand on the documentation theme, the user interface in general should be reviewed with an eye towards user experience, in general. Tooltips and in-game help would go a long ways towards lowering the barrier to entry on this mod - wiki documentation is fine for detailed tutorials and out-of-game browsing, but the first resource the player should have should be right in the game.
I actually find FAR's in-game documentation very hard to read, so I'm not sure you should use it as a model.
However, more tooltips would probably be a good idea. AFAIK only the flight computer has those right now, and their wording is often confusing. I can also see that being a good approach to active vessel, etc.
@MOARdV: on the subject of reviewing the UI, @erendrake said he'd make a mockup of a new targeting window on #107. Once we have that, it might be a good idea to post it on the forum. I'm thinking a blind survey, along the lines of "if you picked the target option in an antenna's right-click menu and got this window, what do you think it would do?"
In what way do you think FAR's documentation is hard to read?
Is it hard to read as in:
1: Hard to understand because the actual documentation is very technical? 2: Hard to read because it's scattered around the mod's interface? 3: Hard to read because of font/format/display issues?
1: I know how to counter. Translating from 'Ngineer to common English is a skill in itself. I've had to develop it to help my explanations of electronics principles. 2: Involves interface design. 3: Involves interface design.
The first and third points. It's too verbose, and the interface isn't really designed for small screens (I have a laptop, and play KSP at 1024×768).
It actually could use more of the second point, IMO. IIRC, it's a big wall of text accessed from one or two buttons.
How about taking a page out of some of the mods for minecraft? A few mods started including craftable books that contain directions and information on the mod. My favorites are Thaumcraft and Rotary craft. The manual set everything up in a tabulated manual interface that goes from page to page with each 'chapter' being a topic.
And top that off with some resize characteristics.
As for verbosity, like I said, that's my realm of expertise. Distilling the data down into information.
I'm adding this to the list of recommended changes for 1.5.0. It's a simple idea, yet should improve the user experience by a lot.
Like I said, I'd be happy to write up the documentation. But I need to know how you guys would like to organize topics so I don't ramble-write.
Regarding topic organization, you can always follow the same organization as the manual (disclaimer: link is to the draft version, please do not redistribute the URL). For example, the player's guide is currently divided into an intro page (which basically defines terms), a "playing" page (which explains the UI, followed by the all-important connection rules), and a "flight computer" page. The parts listing is probably not something that needs an in-game equivalent.
However, I still think more/better tooltips might be a better solution, if only because it's less likely to intimidate new players ("I have to read how many pages???"). On that angle, I'd say start with improving the flight computer tooltips and adding any you think are missing. You yourself have said it's one of the hardest parts of RemoteTech to learn.
A bonus (FOR LATER) would be if the text for the connection rules actually changes based on how the EnableSignalDelay, RangeModelType, and MultipleAntennaMultiplier options are set. But first let's get something that works, we can get fancy later.
Let me get a cold read from you guys of something: http://www.mediafire.com/view/5hdfhdme7z7g0bh/Reentry_Instructions.doc
That's reentry procedures I wrote up as a document for the XR-2 Ravenstar in orbiter. What I write will likely read like that. Though broken down into smaller pieces for individual consumption.
Also, tooltips are wonderful, but verbose manual for all the data is still a must.
Looks pretty readable, and I like the balance between guiding the reader and assuming some common sense. Only disclaimer is that I've never played Orbiter myself, so I don't know what it would be like to actually walk through these instructions.
The "Skills Taught" and "Prerequisite Skills" sections are kind of interesting. Everybody, should I include those in the online tutorials? So far I've mostly been assuming the reader knows how to play stock KSP, but maybe it's better to be explicit about what skills are needed.
I liked the presentation in general. I've tinkered with Orbiter briefly, but I understood enough of it to follow what was going on (and now I want to add a plugin / window for Base Sync in KSP!). I think the "Skills Taught" and "Prerequisite Skills" should be in the documentation in some form. Depending on the overall tone, it would be fine to make it more informal: "To create your first satellite network, you need to know how to place satellites in low Kerbin orbit..."
Regardless, the whole point of the tutorials is to teach. If you spell out what you're trying to teach, it's easier for others to tell you if you're succeeding.
Well, it's effectively this reentry: https://www.youtube.com/watch?v=OiK1Ww6Xisw
Or at least the procedure leading up to it. The video itself starts a little ways into upper interface. But I reviewed procedure as I wrote it by doing it as I wrote it.
The trick of the matter is finding the right amount of verbosity to impart the details that need to be known, while balancing them with enough open and loose wording not to shut brains down. Hence the minor humor and the almost narrative style in the writing.
And it really would be good to define skills needed and skills taught in a tutorial. People need to know what they're learning, how they'll learn it, and what tools (skills) they need to learn it with. That, combined with keeping each tutorial focused in scope makes tutorials very modular and useful. No tutorial should ever do a reentry procedure like mine, and then seguay off onto an in-depth lesson on mass shifting for angles of attack, radiator handling, or any other subjects related to the topic the same way my third-cousin is related to me. Yes, those are all important, but "we need to focus on the now, now." A few micro-lessons (Explanations) are good to have to highlight a 'why' or such other detail*, but that's about it.
- - People listen a lot more diligently to complex instructions if they know the 'whys' behind them.
EX: "Don't do that." vs "Don't do that, because if you do... It explodes."
Some more thoughts on documentation, in the previous document I mentioned a difficulty level, but that's pretty useless if we don't have a yardstick to measure what each 'difficulty' means. If task tutorials include a stated difficulty level, it would probably be prudent to list the levels.
So here's a prelim list:
- BASIC "Defined as a foundation skill or task which can be performed with no prior knowledge of the subject and minimal instruction. A skill or task that is often assumed to be a component part of other more advanced skills/tasks."
EX: Placing an Omni on a rocket or pointing a dish.
- Intermediate "Defined as any two or more combined basic tasks, without regards to order or timing, which have known effect or relation to each other."
EX: Launching an Omni successfully into orbit using direct connection. Establishing multi-dish links.
- Experienced "Defined as any two or more combined Basic OR intermediate tasks that do include order and timing as key parts of correct execution."
EX: Placing an Omni into orbit utilizing the flight computer.
- Advanced "Defined as a series of integrated tasks combining now fewer than two EXPERIENCED operations under low stress conditions."
EX: Programming in orbital maneuvers for a planetary encounter and orbit establishment during an expected, but inconvenient blackout period.
- Expert "Defined as a series of integrated tasks combining no fewer than two EXPERIENCED operations under high stress (time critical) conditions requiring fluid knowledge of the working interface to complete without error."
EX: Remote programming a landing procedure in narrow or unexpected window of opportunity.
PROCEDURE: Any complex task using multiple or repeated tasks to achieve a specific goal. Difficulty of a procedure is defined as the highest ranked difficulty of any task involved.
Starting from "experienced" the descriptions start to sound a bit like legalise. You might want to reword.
For example, I'd replace "under low stress conditions" with "when there is plenty of time to prepare". It's more specific (some players seem to get very stressed playing KSP) but also a bit more conversational.
Also, typo in "advanced": I think you meant "no fewer than"
Apologies for the zombie post, but just saw this in the KSP forum: http://forum.kerbalspaceprogram.com/threads/83305-0-24-2-RemoteTech-2-v1-4-1?p=1436728&viewfull=1#post1436728. Should we make something like that official?