Writing a User Manual

[bearbin]

Do you think we're all ready to start writing? If we're set on HTML I can start to write the templates and CSS code.

[xoft]

What about the storage? You might want to consider preparing it before letting everyone rush in.
I think the GitHub pages approach - creating an un-rooted branch of the repo and storing stuff there - is an interesting approach that could be used here as well; although it has some shortcomings, it is by far the most manageable; short of putting the docs in a separate repo or into the repo alongside the code.

[worktycho]

I'd vote for either a seperate repo that can have github pages turned on or as part of the existing website. The seperate repo is slightly harder to manage then a branch within the same repo but it is easier to use github pages with and it is worth putting the documentation online.

[bearbin]

I'd say a seperate repo, or just a subfolder inside the main repo currently.

[xoft]

Separate repo seems like the best way to go; it can be later added as a submodule, should we wish so.

[bearbin]

OK, great

I'll start to set up the HTML base and CSS.

[bearbin]

OK, I have thought about the system a bit and proposed a system: check it out on the repo https://github.com/mc-server/mcs-book/bl.../README.md

Do you have any suggestions for a better system. Somebody would also need to write the generator.

---

Also, once the generator is written I could set up an auto-updating website to host it on, just needing a CNAME.

[xoft]

The metadata could be even inserted directly in the html structure, as a set of <meta> elements, each on a separate line (to simplify parsing) - this will allow people to actually preview the file in a browser simply by opening it.
The question is, do we even need the metadata? Can't they be substituted by folders / filenames? There's definitely no need for section numbering, the generator can make that

[bearbin]

Yeah, I guess you don't really need it. (apart from the description, if you want a custom HTML description for each individual page in individual mode) It would make the generator a bit simpler, but the folder structure more complex.

[xoft]

The generator can read the descriptioin from html page's <title> tag.