Writing a User Manual

[Narroo]

I think MCServer needs a User Manual. MCServer has almost no documentation and using it relies on a combination of knowing:

1: Already knowing the basics of running a server

2: Knowing the basics of running a minecraft server

3: Being particularly program savy

4: Bugging people on forums with questions that could easily be answer.


The lack of user documentation is so bad, I only found out about the webmanager for the server through an old post on the Minecraft forums.

Currently I'm experimenting with templates on MS Word for a good layout for a user manual. (I'm not good at typesetting though.) My idea is that I'll try to make a skeleton with a bit of the basic information, then we'll add it to github. Everyone can add a bit and review the information in the manual then. What do you think?

[LO1ZB]

I think a wiki solution like Wikia http://www.wikia.com/Wikia would be better that a MS word dokument.

[xoft]

We already do have a wiki, but it has been neglected for so long that it's almost useless by now, and ridden with spammers. So the links have been shamefully hidden. If you think you can bring some light in there, it'd be greatly appreciated. The wiki link is http://wiki.mc-server.org

[bearbin]

Writing a user manual might be a nice holiday project for me. Would you prefer the manual in HTML (wiki) format, HTML (document) format, PDF or some other type?

[Narroo]

Writing a user manual might be a nice holiday project for me. Would you prefer the manual in HTML (wiki) format, HTML (document) format, PDF or some other type?

PDF.

I find online manuals to be messy and inconvenient, plus the website has to be maintained. Besides, we don't want a Wiki- this isn't actually Minecraft. This is utilitarian program with well defined functions; a Wiki is unnecessary.

I'd like a nice "User Manual" PDF to be included with each download. It tells you what MCServer can do and how to do it. Nice, simple, convenient, and to the point.

[xoft]

I personally hate PDFs, mostly due to the poor software support - adobe's a bloatware, foxit can't display some of the advanced pdf features, and there's really no tool to actually edit the pdf file; there are only exporters from other formats.

Why not wiki? We want anyone to be able to contribute the documentation as well, write a tutorial on a separate sub-subject or anything.

[bearbin]

What about a HTML file that has the same format as a PDF? That will not require a PDF reader, and everybody has a web browser.

In response to xoft, I think a new Wiki (old one just needs a nuke and a start again) can coexist with a user manual, as they serve slightly different purposes - a manual just has the basics of running the server and things that you normally need to do, but a wiki has _everything_ people know about MCServer.

[Narroo]

What about a HTML file that has the same format as a PDF? That will not require a PDF reader, and everybody has a web browser.

In response to xoft, I think a new Wiki (old one just needs a nuke and a start again) can coexist with a user manual, as they serve slightly different purposes - a manual just has the basics of running the server and things that you normally need to do, but a wiki has _everything_ people know about MCServer.

It doesn't have to be a PDF. It can be an open word file, or whatever. I just want an easy to read, well formatted (My greatest challenge yet!) manual that tells you how to operate and use MCServer. Not a quick start guide. A manual. If written correctly, user tutorials within the scope of a freshly downloaded MCServer shouldn't be necessary. Plus, I always find that wiki's are horribly designed for user manual style navigation. You want an intro, a table of contents, and then a linearly written document that conveys information in a logical fashion.

While a Wiki could do that, the interface is designed more for semi-random browsing of information, like Wikipedia. If people are going to be editing the Wiki, it's going to eventually get messy and require upkeep to keep it sane. Plus, trolls. There might always be trolls that mess with the Wiki.

An HTML site would work; Git Bash's new user manual is formatted as both an ebook, PDF, and HTML. But, when trying to reference info, I always find navigating through a website slower than a single document. That, and I've seen dead manual links before, which are not nice. Including a proper manual with the program is the simplest and safest solution.

I think a Wiki might be good for miscellaneous things that are not rightly covered in the manual, such as advanced networking, or network trouble shooting, or special plugins or mods. Things that aren't really a part of MCServer but are useful to know. But that would be best kept separate from the manual itself.


I know I probably sound a bit annoying saying this but I always have a bit of an inner groan when I find that the documentation for something is online, and it always gets a worse when I find out it's a wiki.

[xoft]

Online documentation has the advantage of being up-to-date; I agree, that offline documentation is better for the times when you're stuck offline and want a read.

How about a set of HTML files stored in the repository, plus a table-of-contents file Lua-style, with a script that can either generate a clickable index HTML file, or join all the files into a single HTML file with clickable table of contents.

[worktycho]

Another option would be to use jekyll and host it straight onto github pages. Its slightly easier to write than html at the expense of a little flexibility.