Akkarin Posted June 28, 2016 Posted June 28, 2016 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. Quote
Emistry Posted June 28, 2016 Posted June 28, 2016 something that would look like this within one file ?https://github.com/HerculesWS/Hercules/blob/master/doc/constants.md Quote
Akkarin Posted June 28, 2016 Author Posted June 28, 2016 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. Quote
Aleos Posted June 28, 2016 Posted June 28, 2016 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. Quote
Akkarin Posted June 29, 2016 Author Posted June 29, 2016 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 Quote
Emistry Posted June 29, 2016 Posted June 29, 2016 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. Quote
Akkarin Posted June 29, 2016 Author Posted June 29, 2016 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 1 Quote
Skorm Posted June 29, 2016 Posted June 29, 2016 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. Quote
Secrets Posted June 30, 2016 Posted June 30, 2016 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. 1 Quote
Skorm Posted June 30, 2016 Posted June 30, 2016 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.) Quote
Lemongrass Posted June 30, 2016 Posted June 30, 2016 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. Quote
Akkarin Posted June 30, 2016 Author Posted June 30, 2016 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. Quote
Kurofly Posted July 1, 2016 Posted July 1, 2016 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. Quote
Cydh Posted July 26, 2016 Posted July 26, 2016 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 1 Quote
Recommended Posts
Join the conversation
You can post now and register later. If you have an account, sign in now to post with your account.