crazycodr

I found something interresting this morning that can simplify our work greatly and promote easier collaboration on the documentation aspect of Forge and Minecraft. First of all, I love Markdown as a documentation language. Is it very similar to most wiki language but just better and it's pretty much a standard now in community based projects due to GitHub's adoption of it. GitHub flavored markdown is even better at this and there are libraries to parse github flavored markdown and render it to HTML. How i see the reference being built is by generating a markdown documentation using a javadoc scanner and you push the changes to a GitHub profile. The rest of the documentation can simply be another folder in the doc, one for tutorials and one for concepts. So you'd have folders like : 1.6.4 Concepts Tutorials Reference [*]1.7.2 Concepts Tutorials Reference People can fork the documentation and issue pull requests to update the documentation... Makes it simpler to review changes and promotes community work. And then, we could have a server that check's out the documentation from GitHub and use "http://parsedown.org/" to render it to HTML and get it styled easily. What do you think?

I think that documentation must always focus on 3 aspects: - Concepts : They explain the general item of something or a group of things. For example, a really important aspect to conceptualize in minecraft is the concept of Items and Blocks. It's the first thing a modder will want to do and the first thing that every modder should know how to handle. - Tutorials : They explain how to achieve something. Direct links from the concept pages would link to those tutorials. So, how to do your custom "furnace" or "crusher" or "mechanical block", how to create blocks with adaptive structure (block lookups), etc. - Reference : Listing of the different classes and parameters using a javadoc analyser to extract that information. Someone that doesn't know where to look in the code is bound to look for a long time. A well defined wiki with a search engine is always faster to find what you are looking for. User comments, examples, links to corresponding tutorials maybe, etc. The documentation would use a Wiki approach for sure, we need to make version branches so we can keep the whole documentation for each version change. I think documentation should not be open to all, but thats me, i think it's a collective decision of all the initial writters that has to be taken into account. What do you think?

Give that man a jar of cookies for that answer. Thank you for explaining that Jabelar, but i still think, for the good of the whole minecraft modding community, there should be a documentation effort put in place. It would help all modders get the best of Forge and Minecraft... Yes, the work has to be done again on each new supported version but hey, the code can move, but it's not a whole new version each time, some principles stay, some change. So creating a multi-version documentation shouldn't be too hard. If you think at how much time is put all around the web at people creating countless video tutorials, text tutorials and then all the work put into the forums to help each other, i'm sure it possible to convert a bit of that into a documentation base that can be reused over time. I actually like documenting a lot, and if there is support from the community, i wouldn't mind putting my efforts into documenting Forge, FML and Minecraft along with directing a small team of dedicated people that want to make this possible. What would be the best way to launch this initiative in your opinion?

I'll need to check out your docs, but right off the start, it looks good. At least, that's some documentation. Looking at the javadoc comments and interpretting obfuscated source code... that has to be even less efficient than watching 15h of video tutorial about someone trying to do something and not knowing how to explain and do it

Started modding Minecraft a few weeks ago, doing good but simple, but i can't seem to find any api documentation of the classes, hooks, endpoints, enums, etc. Lots of tutorial lingering the world but no documentation it seems. I'm kinda tired reading tutorials that say copy and paste this, do that and it'll work... I want to understand what i am doing and not listen to 13 videos to know how to do a custom furnace with a person that doesn't even seem to know what he's doing! So where is that documentation?