Writing a User Manual

[bearbin]

I'd say we should keep the documentation in-repo, like you suggested xoft. A new wiki might be nice too, but it's not essential.

[Narroo]

Right, so I've been looking up how to make a nice looking looking user manual. This seems to be surprisingly difficult and it seems we might end up using HTML, so I've gotten nowhere on that front. So for now, to get something started, I've written a preliminary outline of the document, and a brief section. I'm not a good writer, and my knowledge on how to run MCServer is spotty. Tell me what you think of this conceptual draft and what you guys think needs to be done to fix it. It does need to be fixed, by the way. I'm under no delusions that I got this right the first time.

[bearbin]

The skeleton looks great, but the connecting example needs some improvement. It seems too windows-centric and also overcomplicates some areas (why look up your IP to connect to localhost, just use localhost or 127.0.0.1.

[Narroo]

The skeleton looks great, but the connecting example needs some improvement. It seems too windows-centric and also overcomplicates some areas (why look up your IP to connect to localhost, just use localhost or 127.0.0.1.

Well, you look up your IP address to illustrate how connecting works. Just typing in localhost is a magic word that doesn't teach the user how connecting to the server works. I at least want to explain that "localhost" isn't a Minecraft specific keyword. The section on LAN connections may possibly cover that though. Also, what's special about 127.0.0.1?

I honestly don't know much about networking or server hosting, so I won't be able to do that by myself, else it's going to be horrendously error ridden. For instance, isn't there a better way of looking up another computer's IP address on a LAN network?

But I'm getting off topic: What I really want to know about is style. How is the style of text? What do you think of it in terms of tone and quality?

[worktycho]

127.1 (thats not a typo, its an alternative way of writing IP addresses) is defined as the loop back address so always refers to the current device.

[bearbin]

I think style is good, pretty much what we would want.

And for visual style, we have CSS if we use HTML so that's always good.

(localhost == 127.0.0.1)

[Narroo]

I think style is good, pretty much what we would want.

And for visual style, we have CSS if we use HTML so that's always good.

(localhost == 127.0.0.1)

Alright. Does that support cut-ins in a easy to implement fashion? For instance, in textbooks, you have have those cut-in text boxes that display tips or other relevant pieces of information that don't fit smoothly into the paragraph. I'd like to mention "localhost" and similar things there. Is that reasonable to do?

[bearbin]

Yeah, it would be really easy to do. Here's an example of how you could do the HTML:

Code:

<aside class="infobox-info">
  Note: Localhost is derpy...
</aside>

You would of course have to define "infobox-info" in your CSS so it displays an indented box with an info icon. You would probably also want to define "infobox-important" and whatever other types of box you might want.

[xoft]

please remove the shcode=html and use only code tag, otherwise this forum displays error popups

[bearbin]

I would have expected the forum to have a code highlighter for HTML

Anyway, done. BTW, is my HTML example semantic enough?