Jump to content

MKS Documentation Development


PocketBrotector

Recommended Posts

Per suggestion by @dboi88, this will be a place to discuss development of KSPedia and wiki documentation for @RoverDude's MKS. 

17 minutes ago, PocketBrotector said:

Here is another flowchart that should show the relationships between all MKS resources. Let me know if I have missed anything. This covers just the basics of conversions themselves, not what parts do the converting or at what rates. In keeping with our earlier discussion, it should be possible for others to edit copies of this, so if someone thinks they can improve on it, they don't have to start start over first. (Most of the other flowcharts I've seen produced for MKS are static, so all of the effort is lost as soon as the mod is updated.)

Right now the wiki looks like it needs a complete overhaul, which is a daunting task. I think that it would be good to establish some guidelines for organizing the thing so that we can avoid a proliferation of redundant pages. Documentation is good but "moar documentation!" is not usually a good thing as it becomes very difficult to use, let alone maintain.

As GitHub wikis do not seem to support Wikipedia-style talk pages, it looks like we'll have to do this on the forums. Obviously there are other folks working on the wiki already... what do you all see as an outline of the content that we'll need?

My initial thoughts:

  • Updated introduction
  • Updated FAQ
  • Explanation of various mechanics
    • Life Support (should link this to the USI-LS wiki, primarily)
    • Inflatables (requirements for engineer EVA, MaterialKits, EC; weight distribution)
    • Switchable bays
    • Efficiency, especially efficiency parts. Machinery requirements, load, etc.
    • Logistics, logistics, logistics! What are the different kinds, and what are the requirements (PartModules? specific parts? crew? max range?!) to make each one work? Most importantly - what's currently implemented; mention what's been been deprecated and what's only planned.
    • Probably a whole bunch of other stuff I'm forgetting
  • Details on each resource (there are about thirty.) What is its purpose and how does one get it
  • Details on each part - Ranger, Duna, and Tundra series. What converters does it have at what rates, is it an efficiency part (or does it benefit from efficiency parts), what crew is required, etc.
  • Tutorials - a step-by-step example of how to colonize Minmus
    • Scanning
    • Ranger base with life support and science labs
    • Duna base with resource exploitation
    • Tundra base with full self-sufficiency
  • Compatibility with other mods - KIS/KAS, EPL, Workshop, etc.

Once we get a minimum viable product up and scrub out all of the out-of-date stuff, hopefully we can get links in the OP, readme, GitHub portal, etc. Then between the wiki and KSPedia, it may even be possible for someone to learn how to use this mod without needing to either puzzle through the configs, or ask a million questions in the 800-page thread...

 

2 minutes ago, dboi88 said:

@PocketBrotector Might be best we start another thread just to keep from overtaking the main release thread.

I've had to balance the line between detail and too much detail quite finely with the KSPedia pages. No one's going to read pages and pages of text, but i wanted to ensure it gave as much useful info as possible on the basics. I think I've got a really good structure laid out that could be further fleshed out for an online wiki. It'd obviously make keeping both updated a lot easier if the general format remained the same.

If you want to start a new thread (not sure where is best) and ping me we can discuss further.

To add, great to see some more people willing to invest their time to help others.

 

Link to comment
Share on other sites

@notthebobo @Crabman @PocketBrotector

It's probably best we decide where to put everything while the new wiki is worked on, so all the changes can be discussed and kept track of. It'd be best if someone took main control over that. So it'd have to be someone willing to get everything set up and fleshed out from the XML file of all the new stuff and realistically be able to spend time on it regular for at least the next few weeks until it's all done. We'd need to pull in some of the other useful info I've not included and then fluff it out from there. 

Anyone willing to take charge on that front?

There's a rough XML sheet here of all the text elements I've got so far. It's a bit weird, it's backwards with the first pages at the bottom.

This is the structure

USI - MKS
0 - 0 MKS
CoreConcepts
1 - 0 CoreConcepts
Ranger Series
2 - 0 Ranger Series Simple
2 - 1 Ranger Part List
2 - 2 Ranger Inflatables
Duna Series
3 - 0 Duna Series
3 - 1 Duna Parts
Tundra Series
4 - 0 Tundra Series
4 - 1 Tundra Modules
4 - 2 Tundra Parts
4 - 3 Tundra Inflatables
Base Construction
5 - 0 Base Construction
5 - 1 Konstruction Parts0
5 - 2 Landing Parts
5 - 3 Connecting Parts
5 - 4 Construction Ports
5 - 5 Servos & Magnets
5 - 5a Konstruction Examples
5 - 6 Base Locations
5 - 61 Base Locations Cont.
5 - 6a Base Examples
5 - 7 Advanced - KIS
Mining & Manufacturing
6 - 0 Mining & Manufacturing
6 - 1 Scanning
6 - 2 Extractable Resources
6 - 3 Resource Extraction
6 - 4 Resource Processing
6 - 5 Parts & Supplies Manufacturing
6 - 6 Advanced - Career Funds
Logistics
7 - 0 Logistics
Habitation
8 - 0 Habitation
8 - 1 Habitation Parts
8 - 2 Habitation Advanced
Life Support
9 - 0 Life Support
Rovers
10 - 0 Rovers
10 - 1 Akita
10 - 2 Karibou
10 - 3 Malumte
Ship Building
11 - 0 Ship Building
11 - 1 ExtraPlanetaryLaunchPad Basics
11 - 2 ExtraPlanetaryLaunchPad Parts
11 - 3 ExtraPlanetaryLaunchPad Advanced

Efficiency & Load
12 - 0 Efficiency & Load
Crew Training
13 - 0 Crew Training
Med Bay & Colony Supplies
14 - 0 Med &colony

https://drive.google.com/file/d/0B_nRjcqonDoUMTJOZGU2QUhpbHM/view?usp=sharing

Link to comment
Share on other sites

There was some mention of a Github for the wiki (as in: For in-development text and assets).  I'm willing to have that in my account (and open to others for commits) if no one else wants to have it - but since I'm still stuck in KSP 1.1.3, I may not be the best choice.

Link to comment
Share on other sites

Hi @DStaal

I've created a GitHub repo with all the images and Unity project files here for the KSPedia entry https://github.com/dboi88/USI-MKS-KSPedia for now i'm only going to be using it as a backup system but feel free to pull any images you want to use from there. I only ask you credit them. 

I'm going to write up a clear and correct copy of all the text from the entry into a text file on the repo once i'm done with [images], [diagrams] & [tables] noted where people can post issues and PR's for changes.

FYI i'm willing to do the same thing in there for a bigger wiki that we can then update from to Roverdude's wiki. It'd be much easier to do once I've finished the KSPedia and i'd be willing to put in the time to manage it and i'd be happy to leave to others to commit changes once i'd set it up.

So unless someone really wants to get going asap i could get that up and running in a week or so once the KSPedia entry is complete.

@PocketBrotector I've left a comment on you're flow chart. You missed chemical's for the refined exotics process. Other than that it's great, much better than the one i'd been playing around with. Do you mind if i try and put a little workflow together to strip that into an image, resize/work as appropriate to it can easily be updated in the KSPedia entry?

Link to comment
Share on other sites

I'm learning how GitHub works, but shouldn't the KSPedia artifacts be in @RoverDude repository?  Is it possible to include the KSPedia in his mods, or are they a separate install?  If they can be included(and RD concurs), having them merged in one repository seems o make the most sense.

Another bonus is that I think the KSPedia images could be used in the Wiki if they are in the same repository (I'll have to test that out tested, can paste with full URL so actually any site will work).

Edited by notthebobo
Clarified that images in the repository can be used as well as external images
Link to comment
Share on other sites

The KSPedia work looks like it will make a fine backbone for the wiki... it would be primarily a matter of formatting for Markdown and then adding more details as desired. Like you said, it would make sense to wait until KSPedia is complete before converting it. The only other caveat I can think of is that basic life support  (habitation, recyclers, and agroponics) should point to the USI-LS wiki, while MKS docs should cover the advanced life support (organics and colony supplies).

Please feel free to use the flowchart however you you see fit. Once I created it, I found that the software wouldn't let me directly as an image without a paid upgrade, but it should let you create a copy in case you want to divide it into multiple sections or whatever. We could potentially fit more detail if there were separate charts dedicated to, say, basic & advanced life support & industry.

Link to comment
Share on other sites

RE: things to do, here's what I laid out in the Wiki: ToDo page before.  By no means complete, but it shows where I was headed.  The slides show where my ideas on how to present the next section of work on converters in the list below.

October 2016 - notthebobo updates

(Done) I am first of all focusing on deprecating the previous Parts pages and then creating the new parts pages, divided into:

  • Ranger Series (Done)
  • Duna Series (Done)
  • Tundra series (Done)
  • MKS Others (Drills, construction help, landing assistance, EL (Done)
  • USI-LS (update for 0.5.0) (Done)

(TBD) The next focus would be on description of the converters that exist in the parts:

  • Resource (e.g. EC to Dirt for drills)
  • Energy (e.g. Plutonium-238 to EC)
  • Supplies (e.g., Mulch + Fertilizer = Supplies)
  • Colony Supplies (not sure how this works yet, may be part of the Supplies section)

(TBD) There should be an update to the home page that describes then links to three separate pages on the three strategy goals:

  • Life Supply
  • Habitation
  • Science

(TBD) Finally, someone with better understanding of the dynamics can tackle the Efficiencies, multipliers, and effect different skilled Kerbals have on different parts/processes.

In the meantime, a quick how-to for first base, both orbital and planetside/munside appears to be what most people are seeking.

Link to comment
Share on other sites

7 minutes ago, notthebobo said:

I'm learning how GitHub works, but shouldn't the KSPedia artifacts be in @RoverDude repository?  Is it possible to include the KSPedia in his mods, or are they a separate install?  If they can be included(and RD concurs), having them merged in one repository seems o make the most sense.

Another bonus is that I think the KSPedia images could be used in the Wiki if they are in the same repository (I'll have to test that out).

I don't think RD would want to ever manage the KSPedia entry himself, it's a hell of a lot of work i think he'd drop it if it was out of date and no one was willing to step in. He will include it in his repo once complete but probably only the actual asset bundle. Yes it will be included in the official release. You should also be able to link to the images from my repo into any of the wiki's you want.

5 minutes ago, PocketBrotector said:

Please feel free to use the flowchart however you you see fit.

Cheers 

@notthebobo Agreed, one of the main things i think the wiki should be geared towards is really well written tutorials.

27 pages done, only 18 to go  . . . 

Rv26QJ7.png

Edited by dboi88
Link to comment
Share on other sites

1 hour ago, dboi88 said:

It's probably best we decide where to put everything while the new wiki is worked on, so all the changes can be discussed and kept track of. It'd be best if someone took main control over that. So it'd have to be someone willing to get everything set up and fleshed out from the XML file of all the new stuff and realistically be able to spend time on it regular for at least the next few weeks until it's all done. We'd need to pull in some of the other useful info I've not included and then fluff it out from there. 

Anyone willing to take charge on that front?

There's a rough XML sheet here of all the text elements I've got so far. It's a bit weird, it's backwards with the first pages at the bottom.

This is the structure <snip>

https://drive.google.com/file/d/0B_nRjcqonDoUMTJOZGU2QUhpbHM/view?usp=sharing

I'm looking over the file but it appears all the XML tags have been stripped out, so its a bit of a struggle at this point.

It looks like there's overlap in the parts sections you've created and the part sections that have already been updated in the Wiki (see "Parts: Dun Series", "Parts: Ranger Series", and "Parts" Tundra Series".  They're easily lost because the old parts pages are still out there.  At some point, they need to be archived/whacked.

Link to comment
Share on other sites

4 minutes ago, notthebobo said:

I'm looking over the file but it appears all the XML tags have been stripped out, so its a bit of a struggle at this point.

It looks like there's overlap in the parts sections you've created and the part sections that have already been updated in the Wiki (see "Parts: Dun Series", "Parts: Ranger Series", and "Parts" Tundra Series".  They're easily lost because the old parts pages are still out there.  At some point, they need to be archived/whacked.

Apologies, that was an attempt to make it more readable, see the full XML file here https://github.com/dboi88/USI-MKS-KSPedia/blob/master/MKS KSPedia/Assets/XML/mkskspedia_kspedia.xml

There should be an overlap for everything because i'm trying to cover everything in the KSPedia, but the way it had been categorized didn't really transfer well over to the structure you're stuck with in Unity.

Basically whoever decides to get on with the work should decide their method. Whether to simply update the wiki directly as has been done already or build a whole new version to be copied over once complete.

@notthebobo i think it might be easiest if people give you a shout with new diagrams, paragraphs, tutorials ect. to be added to the wiki as you've been doing most of the updating there so far. Feel free to grab any of the images here https://github.com/dboi88/USI-MKS-KSPedia/tree/master/MKS KSPedia/Assets/Pages

Link to comment
Share on other sites

I'd like to volunteer...ping me if I can help with anything.

One comment I'd like to make is that in a few places, I see that people are cutting and pasting the in game descriptions from the parts.  While they tend to have a certain style, they are not always real descriptive and repeating it in other places doesn't really add value.  I was thinking about trying to make a part template that will contain all reference information, like it's exact functionality, whether it needs a profession, whether if consumes, distributes, or both, etc.

Let me know if there is any way I can help, thanks

Link to comment
Share on other sites

10 minutes ago, Gilph said:

 I was thinking about trying to make a part template that will contain all reference information, like it's exact functionality, whether it needs a profession, whether if consumes, distributes, or both, etc.

Stuff like this?

YOCkCCn.png

I've tried to have an overview page of each 'series' of parts with basic descriptions and then different descriptions and relevant stats in each section. I also hope to put tables of hard stats in another section as well for quick reference purposes. I need someone to come up with some first though. So you could help in that area.

Link to comment
Share on other sites

1 hour ago, dboi88 said:

Apologies, that was an attempt to make it more readable, see the full XML file here https://github.com/dboi88/USI-MKS-KSPedia/blob/master/MKS KSPedia/Assets/XML/mkskspedia_kspedia.xml

There should be an overlap for everything because i'm trying to cover everything in the KSPedia, but the way it had been categorized didn't really transfer well over to the structure you're stuck with in Unity.

Basically whoever decides to get on with the work should decide their method. Whether to simply update the wiki directly as has been done already or build a whole new version to be copied over once complete.

@notthebobo i think it might be easiest if people give you a shout with new diagrams, paragraphs, tutorials ect. to be added to the wiki as you've been doing most of the updating there so far. Feel free to grab any of the images here https://github.com/dboi88/USI-MKS-KSPedia/tree/master/MKS KSPedia/Assets/Pages

The XML file makes much more sense, thanks.

I'm fine coordinating the pages.  I don't want to be a roadblock, however.

Link to comment
Share on other sites

1 hour ago, Gilph said:

II was thinking about trying to make a part template that will contain all reference information, like it's exact functionality, whether it needs a profession, whether if consumes, distributes, or both, etc.

In the current Wiki, I approached it like shown below.  It quotes (literal Wiki quote) the in-game description and the basics about the part (cost, mass, crew, storage abilities, etc.).  What it doesn't have are the converters, life support modifiers, habitation modifiers, etc, because each of those needs a context to explain them.  I was thinking that there would be a section on each of the USI-LS game strategy points (supplies, habitation) as well as MKS specific strategies (mining, manufacturing, recycling, EVA repairs, etc.) and having details about each module in those sections.  

The bottom-line question is, when people access the Wiki, are they looking for all information on a part in one place (e.g., here's what a Tundra Assembly Plant can do) or are they looking for what parts will perform a specific function (e.g, extend the habitation constraint, decrease the supply construction, allow recycling of mulch).  Answering that question really affects how the wiki should be put together.  The approach I get from dboi88's KSPedia structure is that sections 2,3,4, and 10 are trying to answer the part specific questions while the other sections are for describing the strategies of the game, which is a perfectly valid strategy that aligns with how the rest of the KSPedia is constructed.

Sample from the Wiki:

MKS Ranger Agricultural Module

Expanded Ranger agriculture module

An expandable greenhouse that can be configured as an algae-based farm and biological filter using either recycled waste (yuck!) or local resources (either substrate or dirt, plus water). Requires fertilizer, and can be used to supplement larger greenhouse-type modules. Ensure an experienced scientist is on board for optimal efficiency.

Cost Mass (T) Max Crew Crew Requirements
16,320 1.251 2 Module must be deployed

The following resources may be stored in this module:

Resource Default Max
ReplacementParts 200 200
Construction 0 1,000
Machinery 5 500
Recyclables 0 500
Mulch 0 100
Supplies 0 250
Fertilizer 0 100
Edited by notthebobo
The Ranger site now links to the KSPedia pictures. Pretty!
Link to comment
Share on other sites

1 hour ago, notthebobo said:

The bottom-line question is, when people access the Wiki, are they looking for all information on a part in one place (e.g., here's what a Tundra Assembly Plant can do) or are they looking for what parts will perform a specific function (e.g, extend the habitation constraint, decrease the supply construction, allow recycling of mulch).  Answering that question really affects how the wiki should be put together.

The answer is really "both." MKS is complex enough that we need all of the above in the documentation: general descriptions of parts or resources, complete explanations of particular mechanics, and tutorials or strategy outlines saying "if you want to accomplish X, first you need Y and Z." I realize that this may not be the most satisfying answer, but that's what I think would be most beneficial based on years of trying to keep up with the mod. I've typically found myself wondering:

  • Okay, what's the big picture here again? What are the things that I can ignore, and what's going to be absolutely required, based on my objectives? (Short-term life support vs complete self-sufficiency, research lab vs refueling outpost vs vessel construction, etc.)
  • What does this part do now? And what are the differences between the Ranger, Duna, and Tundra variants? And what are the "hidden" requirements for full functionality - profession, efficiency parts, etc.?
  • Oh, this produces [for example] Organics... what do those do again?
  • Huh, this says something about "logistics" [or "inflatable", or "BulkConverter", or some other MKS-specific mechanic] but I can't figure out how to make it work...
  • Can I just see an example of something that works so I can tinker with it?

Even the specific quantities involved (e.g. the ratio of MetallicOre consumed to Metals produced) might as well be included since we're going to be looking at them anyway in the course of examining the part configurations.

1 hour ago, Gilph said:

One comment I'd like to make is that in a few places, I see that people are cutting and pasting the in game descriptions from the parts.  While they tend to have a certain style, they are not always real descriptive and repeating it in other places doesn't really add value.

The limitation of the in-game description is that they're designed to be evocative or funny rather than deeply informative. If the Kerbitat claims that it provides "all the comforts of home," that's very colorful but it tells me exactly nothing about how it differs in practical terms from, say, the Colonization module. 

I try to think of it in analogy with the stock KSP mechanics. When I download a part pack that includes engines, I generally skip the verbal description entirely and look at the stats, which tell me the fuel efficiency, the thrust and mass, whether it's better suited for atmospheric or vacuum use... of course, before I could make sense of those stats, I had to get a sense of how the Tsiolkovsky rocket equation worked. Those are the mechanics of stock KSP; MKS has its own mechanics (resource chains, logistics, and so on), and so its documentation should explain

  • the general strategy: "Build a Ranger base capable of life support before you tackle a huge Tundra base capable of off-world construction" might be the MKS equivalent of "when you're first trying to orbit, start out going a straight up and turn east very gradually..."
  • the particular mechanics: "here's what you need to inflate that greenhouse" is the equivalent of "here's how you need to set up RCS thrusters to get full control for docking"
  • the specific numbers: "this Tundra module has a better conversion rate than the Ranger module" is the equivalent of "here's why the Poodle is better than the Mainsail once you've reached space..."
Edited by PocketBrotector
Link to comment
Share on other sites

Ok, I've pulled together a plan that I think will map well to the KSPedia.  I've defined it as a Site Map page on the Wiki.  If you decide to take one of the pages, please amend your name to the sitemap so we know someone's working it.

The Kore Design page is really the main page as it covers the main topics, referring to other pages where more detail is provided.  

Site Map

This page captures the planned/in-progress re-do of the site to align with patch 0.50 and later.

Link to comment
Share on other sites

One thing that's missing from that - and that I know was appreciated - is documentation for other mod developers who want to inter-operate with MKS:  How to activate the various mechanics in your parts, and what is appropriate, balance-wise.

It's a more technical audience, and they can always refer to the rest of the wiki for details on how things work in-game, so it can be very abbreviated, relative to the rest of the wiki.

Link to comment
Share on other sites

Outline looks good and I imagine it will evolve as things are fleshed out. Earlier this evening I created a Resources reference/glossary that incorporates the flowchart and provides a (deliberately terse) description of each resource's relationship to its precursors and products.

I will reiterate that I'd like to see documentation of USI-LS features primarily on the USI-LS wiki rather than the MKS wiki. MKS extends and expands upon USI-LS concepts, but there are plenty of people who use life support without MKS, and they need support just as much as the MKS users. Best not to conflate the two different mods as it will confuse the folks who need help the most. 

MKS wiki should point to the USI-LS wiki where possible for the following topics:

  • Habitation - kerbal-months, hab multipliers
  • Recycling
  • Agroponics (Mulch + Fertilizer = Supplies) - this exists in both USI-LS via the nom-o-matics and MKS via the various ag modules
  • Supplies, Mulch, Fertilizer
  • Fertilizer production using Ore

Advanced life support topics are specific to MKS and include:

  • Medical bays and colonization modules
  • Purifiers (recyclers that consume Water)
  • Organics and ColonySupplies
  • Cultivation (Dirt/Substrate + Water + Fertilizer = Supplies) and Agriculture (Dirt/Substrate + Water + Fertilizer + Organics = more Organics)
  • Fertilizer production using Gypsum or Minerals
Link to comment
Share on other sites

20 minutes ago, notthebobo said:

Added.  Not sure who is the best POC for any modding changes.  If you know someone, let them know we're looking to update.

I did it for the previous version of the wiki - but it was written using a combination of RoverDude's docs and my own experimentation.  RoverDude hasn't released his docs for this yet (his balance spreadsheet should be a good starting point), and I can't run the current version, so that path is likely to be blocked for the short term.

As much as anything else I wanted to make sure it stayed on people's radar.  And even outdated, the current docs provide some starting point - most of the part modules involved haven't changed, as far as I can tell, it's just balance tweaks and some behavior changes.  (There are a couple of new part modules that look to be related to the switching production/converter slots.)

Link to comment
Share on other sites

3 minutes ago, notthebobo said:

Good points about the USI-LS wiki.  Is anyone working on it?

I wasn't aware that Fertilizer production was in USI-LS.  What module does the conversion from Gypsum or Minerals?

Not lately, but I was one of the people who built it out much earlier in the year. It looks like DStaal and a few others had worked on it since then. Would need to be updated primarily to bring the values up to date to v0.5.x

Fertilizer production in USI-LS is pretty simplistic - it just adds an Ore -> Fertilizer option to one of the stock ISRU. Gypsum and Minerals are strictly MKS.

One more thought... we should make a pass through the existing pages and examine whether they should be incorporated into the updates or just deleted. There are a few that are blank, explicitly outdated, or have inscrutable titles/content. Based on the broken link in my signature I think that renaming a page is as good as deleting it, anyway, since it breaks all links (GitHub it seems is not as nice as MediaWiki when it comes to redirects). Supposedly GitHub wikis are implemented as repos, so if we "delete" anything of value, it should be possible to recover it afterwards with some digging... haven't tested it though.

Link to comment
Share on other sites

If someone wants to tackle USI-LS, that would be helpful.

As for deleteing pages, you're right that renaming them does not change the links on other pages.  I've started renaming pages that I think are OBE with "ZAPPED AS OBE" so they aren't gone, but they're grouped together at the end of thee page index and "out-of-the-way".

Link to comment
Share on other sites

@notthebobo Good work on adding the images, they look great. I don't know if you noticed most of the parts for the 'Ranger' series are on one image, this will change at some point in the next few days as i'm going to go back and split them out. (it was an early and in vain attempt at optimization) so i'll let you know when I've done that so all the parts can have their own image.

In regards to the 'Tundra' module image and module numbers will you be able to overlay one image over the other? if not let me know and i'll knock together a set of images with them already on for the wiki. The same will be done for the Duna modules shortly as well.

Can we also add in a section on the Wiki for 'Konstruction' and 'Reactors' seeing as they're bundled with MKS now.

Link to comment
Share on other sites

This thread is quite old. Please consider starting a new thread rather than reviving this one.

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

×
×
  • Create New...