/doc/ modernisation

[Akkarin]

As we've been using Github for a while now, do you think that files included in the repo should be brought upto modern standards? May as well take full advantage of the tools we already use.

 

I'm talking about /doc/ and the samples folder.

 

Github has this marvellous markdown capability and we're pretty much ignoring it. The only place it's used is in Readme.md, and we even have a .txt variant of that for no reason whatsoever.

 

Updating /doc/ to use Markdown will provide us with the ability to link directly to files/lines within the repo, include snipets, hyperlinks, even example images for users viewing the docs via github itself.

 

It just seems such a waste to have those monstrous text files gathering dust when we can be using them for so much more.

 

And before anyone comes up with some cynical ".md extension" rubbish, .md can be read by all text editors too. And via the web. And is still readable in plain-text format for "backwards users compatibility". So no excuse really.

[Emistry]

something that would look like this within one file ?
https://github.com/HerculesWS/Hercules/blob/master/doc/constants.md

[Akkarin]

something that would look like this within one file ?

https://github.com/HerculesWS/Hercules/blob/master/doc/constants.md

 

Jesus that file is heavy...

 

And no, that's a pretty ridiculous reason to move to markdown. All it's using is just unordered-lists. In that particular example i would suggest adding a constants/ dir to /docs/ and separating some of those groups in order to expand, link, describe, example usage, etc. Just adding list options to a big-ass list like that is a waste of time.

[Capuche]

Hmm we need to make a sample.

[Aleos]

I agree. It would be great to port over to a standard markdown. Linking across Github would be a great feature with it as well. It could also pose a great effort in the revitalization of the Github wiki so rAthena can drop it's end of the wiki and start focusing on just being a forum again.

[Akkarin]

Hmm we need to make a sample.

Samples incoming

Aleos don't beat me to the punchline, this is a stepping stone to sorting out the wiki once and for all.

This is a very basic example. Not really much to do with this file but chose it as it's small and something i could whip up quite quickly:

https://github.com/Akkarinage/rathena/blob/docupdate/doc/map_cache.md

[Emistry]

uhm, but when it come to the script_commands.txt its gonna be a god damn long and heavy contents.

 

if rAthena decided to remain every single script command within same text files,

then it probably end up like the sample from Herc I shown above.

 

if rAthena decided to separate each script command into their own individual .md files,

it look short/simple/nice,

but it lose the convenience where you can find all script command within 1 text files

especially when you try to view it in any text editor.

[Akkarin]

script_commands.txt will always be a challenge. We can't break it up, but it needs a damn good sort through. There's command descriptions that are outdated, incorrect and poorly worded.

That being said, I have a plan and will get a test commit pushed soon

[Skorm]

I'm going with the current minority on this one...

 

[|||] Pro:

• I like the idea of optimizing things.
• Hyperlinks are cool.
• Engrish is sometimes mistakenly used in the old documents.

 

[|||] Con:

• I've been using the old text documents for years with no problems.
• I'm probably the only one here that thinks this, but I don't hate the Wiki.
• I don't like the idea of loading a webpage everytime I want to view something.
• Windows doesn't natively know what to do with .md files creating another barrier for beginners... (I can already hear the support leaders cries.)
• Editing our documents becomes more convoluted.

[Secrets]

I'm going with the current minority on this one...

 

[|||] Con:

• I've been using the old text documents for years with no problems.
• I don't like the idea of loading a webpage everytime I want to view something.
• Windows doesn't natively know what to do with .md files creating another barrier for beginners... (I can already hear the support leaders cries.)
• Editing our documents becomes more convoluted.

1. Old one being fine doesn't mean that it can't be improved.

2. Markdown is supposed to be human readable even in its plain text format.

3. If they don't know how to open a .md file using text editor they might as well as shut their server down.

4. You can just copy-paste the template from another command.

[Skorm]

 

1. Old one being fine doesn't mean that it can't be improved.

2. Markdown is supposed to be human readable even in its plain text format.

3. If they don't know how to open a .md file using text editor they might as well as shut their server down.

4. You can just copy-paste the template from another command.

 

 

I'm not saying you're wrong, but you'd be surprised.

 

(As I side note I did look over the RAWs from the sample and they looked readable... Although my position is still neutral.)

[Lemongrass]

It would be nice to see some real samples of markdown to be honest.

You stated linking lines etc is possible.

 

As for script_commands.txt:

In my opinion this file should become an overview file, which links to subdirectories/subfiles for each chapter + each command.

Each command should also contain or even better link/include a reference sample script.

Additionally it would be good to also get some test cases for each command to be able to ensure that it is still working.

But this is a different story.

[Akkarin]

It would be nice to see some real samples of markdown to be honest.

You stated linking lines etc is possible.

 

As for script_commands.txt:

In my opinion this file should become an overview file, which links to subdirectories/subfiles for each chapter + each command.

Each command should also contain or even better link/include a reference sample script.

Additionally it would be good to also get some test cases for each command to be able to ensure that it is still working.

But this is a different story.

 

Most of the commands in script_commands.txt already have example usage scripts in the doc itself. I don't see why we can't have specific script samples in the /doc/samples/ dir, as that's what it's there for. However, I don't think breaking the file up into grouped commands is a good idea.

[Kurofly]

Doesn't seem like a really good idea to me..

 

Sure I'd love to see .md files as documentations and it's true that we have some monstrous doc files. But that's gonna take a hell lot of time!

A big effort has already been put by devs to make the plain texts as easily readable as possible, I personnaly find it easy to read and people are already used to them.

 

Since there are way more people used to those files than people who are not (not 100% sure of that though ^^) I'd say this amount of work is not really worth it

 

There's also one thing I'm afraid of, if you look at the file emistry posted, to me it looks even more horrible than it looked before! Bulleted lists are nice but it becomes a pain when there are too many of them. I'd especially pay attention to that because if you considerer some files monstrous that's definitely something you should avoid.

 

Even so, links, bold texts, and text size would be some really cool features to see in doc files.

 

It all depends on the way it's done, it can be really nice but one thing for sure is that it's gonna take muuuuuch time, that's why I'm a bit reluctant to this idea.

[Cydh]

It'll be good... or not. Only if I can open markdown file in 'pretty view' locally (except Chrome extension).

 

3. If they don't know how to open a .md file using text editor they might as well as shut their server down.

 

TL;TR

Mark down file will be pretty good of Github integration, but not for local usage, but still I want to see the docs are human-readable.

Well, just make README.md on /doc/, wite summary there, HIRE SOMEONE AS DOC MANAGER then whip them to make .md version of all rAthena docs, put the links on /doc/README.md, uploa dthe .md docs on different repo :v