Suggestion for Community Docs
Monkey Forums/Monkey Programming/Suggestion for Community Docs
| ||
| The AIM of this project is TO: 1. Make docs contributions easier than any wiki 2. Make viewing & reading better than the current docs 3. Adding docs-support for external frameworks 4. Make searching and browsing easier than current docs 5. Keeping an up-to-date list of frameworks, modules and code-snippets 6. Provide better tools for writing a tutorial or article than these forums 7. Let newcomers and yet-to-adopt users a more wonderful time I made a mockup in Wordpress of a potential future community driven documentation system. You can see it in action here: gamecrater.net [DOMAIN IS TEMP, testing only, pretend it says http://www.monkeycoder.co.nz/Docs or LearnMonkey.com] Features: *Improved Official Docs Readability *Improved Dynamic Search *Works with ANY resolution width *Community Contribution easily possible *Monkey Syntax Colored Code Editor *Included are the Official Docs *Export to Offline Html Docs *Add docs for your framework *Articles *Tutorials *Code Archives *Updates on all things Monkey *Powerful Comment System *Module Library Note1: The idea is that Framework or Module devs can get their own section of the site. Note2: If admins for each section are chosen with care I hope the docs can keep a high level of correctness. Note3: My wish is for it to be hosted by Mark and used as the official system in Monkey, but I think we should/need to *prove* it works first Do you think it is a good idea? Improvement? Possible pitfalls? |
| ||
| Good start. :-) |
| ||
| First of all, BRAVO!, wordpress quite simply KICKS ASS!. I think Mark should move this whole site over to wordpress and then integrate the docs, the forums, and the apps section all into the one thing, not only will it improve readability of the site, not only will it improve the docs by allowing as you have outlined community contributions but it will make the whole site a lot easier for mark to manage, to maintain and to update, not to mention its one of the most secure cms systems on the web due to its popularity and continued support. |
| ||
| This really looks nice and it would be a fantastic resource. |
| ||
| Thanks! Taiphoz, added you as Editor so you can edit everything. If you are familiar with Wordpress plugins & settings let me know and I'll give you full admin access! I think one day Mark will be ready for Wordpress. It is quite easy to add a professional forum. The App section would also be simple since we can inline flash & html5 in any page. In the future the idea is that we can assign roles so different sections can be dedicated to a group of users, such as diddy to the diddy team and so on. I was hoping it would be possible for us to have flash and/or html5 demos inline. Those kind of "interactive" tutorials are so great, seen a few in flash. 1. They have a piece of code. 2. Below is a small interactive frame running that very code. 3. Description on what happens. Can it be better? :) Found this WYSIWYG editor: http://xing.github.com/wysihtml5/ and this: http://jejacks0n.github.com/mercury/ |
| ||
| Yeah that would be very cool. and yeah I have been using wordpress for years now, moved to it after using other cms systems like e107, php-nuke joomla and some others, once i hit wordpress i never looked for another cms. |
| ||
| Another amazing thing Mark could do if he made the jump to wordpress is install it with the MU options enabled, back in the day over in the blitz forums there was the work log, well here, with wordpress mark could actually allow developers to register a blog where they could blog their progress all hosted in the one place. Sadly I think most of this will be falling on deaf ears, I think this plus the move to git might just be to much for him. its a shame really, but that aside YEAH COUNT ME IN> more than happy to help where I can. |
| ||
| (Paul, do you do WordPress consulting/work for hire? I have a friend who might could use some help in the future.) |
| ||
| This looks very nice! I will have a better look at it. |
| ||
| c.k. no mate, all my WordPress experience comes from just personal use, coming up with things I want to have on my site and then learning what was needed to make it happen and have work the way I wanted. So my love for it comes from using it for a few years now and every thing I have wanted to do with it, I have either been able to download a plugin right out of the box, or had to write a little bit of php to do it on my own, all the other cms' I have used at one point or another I have always hit a wall, something I wanted to add that a given cms' would not allow me to add, that's normally what prompted me to find a better cms, since i started using WordPress I have never needed to look any further. If your friend is looking for WordPress help the best place would be their forum, its a lot like here, an almost endless supply of people willing to help out if your stuck with something. |
| ||
| Looks quite good. An up-to-date set of online docs with the possibility of community editing? That's me sold on it :) |
| ||
| I hope we get enough support for this project to take off. I asked Mark about this and the only big concern he seem to have was that he had previous experience where community docs had resulted in miss-information. He was positive to help contribute himself if the docs works out. I'm happy to spend time updating the docs, writing tutorials and structuring the site - my only concern is that to few users will use it as a viewing tool because to few framework devs use it as a writing tool. If you are building a framework or module Please let me know of any reason you would hesitate to use this for your framework/module. It will always be 100% free by the way. |
| ||
| If you are building a framework or module Please let me know of any reason you would hesitate to use this for your framework/module. Please tell me, what would i gain from putting many many hours into your site? Which advantage would i have spending more extra free time on this? Reasons? 1) Not officially supported and not an official BRL site. 2) Over the last weeks I have build my own tool to create html help files from the sources automatically. 3) I have more but then i would step on some peoples toes here. Let's not do that. :-) |
| ||
| I have an alternative suggestion of using github to host docs, that way it's not dependent on an individual's hosting (like all the other blitz wikis have been). People can do a pull request to update the docs, they can also fork them and update their versions as needed and nobody can destroy the docs with spam (except in their own fork). |
| ||
| The hosting cost are already paid for this site and can easily be moved. But it is up to Mark to say yes. I have offered to give the site away for free and help in the transition if need be. I also want this to be official and/or hosted by Mark. The idea with community docs is not that big if they can't *easily* be changed. We had a wiki before that was a pain to edit, even tough I had an account I never got around adding to it for this very reason. Going through git would be an even higher barrier than the wiki. The idea here is to lower the barrier of contribution and at the same time increase the access of information so it is easier to find. Even better if contribution happens on the same platform that we all use to browse. Every day people's questions are answered in these forums, what if even few of those made it back to the docs. In just a few months the docs would be super solid, instead of lacking. Today except very basic things, the only way to find an answer is to search the forum. It takes so much time. For external frameworks and modules it is even worse. That is the problem I want to solve. |
| ||
| As long as it's easy to contribute to, but also moderated, there really isn't much to lose from centralised online docs. For the target I'm working on, I'm having to decipher the underlying code structure to see exactly how everything fits into place. Before I started, I searched the forums to see if there was much information about this, but there's not. The information I did find was using the old targetting system, so I had to adapt it to the new one ... once I had figured out how it worked. And if someone else wanted to start creating a new target, they'd probably have to go through much the same as I have. Sure, I could write a complete tutorial, but that takes a lot of time, which could be completely wasted if nobody can find it. The forums can be used for stuff like this, but it can quickly become a mess, and you have to read through loads of replies to get to the information you need ... or hope you get lucky with a search. Moderated collaborative docs is the sort of half-way house for things like this. Can still discuss things in the forums, but also add bits of useful information into the docs, where it can be easily found. |
| ||
| I have the Monkey site,why would i need this. |
| ||
| MrB, I don't think the Monkey site docs are as comprehensive as they could be, and we'd rather let mark work on monkey, not docs, especially when contributing to docs is so easy. |
| ||
| https://github.com/blitz-research/monkey/tree/master/docs/html Contribute to docs here perhaps? |
| ||
| MrB, you have the Monkey site, really? Click on the Wiki link above and tell me what you get. 404 here Contributing to docs through git isn't ideal. There needs to be an easy way for those that don't use git to contribute, and to view them too. |
| ||
| MikeHeart as he said his hope is that mark makes these docs offical and takes over their hosting so it is all offical and linked through ted/monkey , if you cant see the benefit of having the docs for your module included within the main monkey docs then you might want to think about it some more. Now granted their not official at the moment, and they wont be UNLESS it gets initial support, its that old Lottery thing, Guy complains to his mate, I don't play the lottery, I would never win, his mate replies you cant win if you don't play. So many people complain about the poor docs, monkey docs are lets face it some of the worst on the net, people moan about it all the time, so if they bother you, or have bothered you at all at any point, this would be your chance to help improve them. |
| ||
| Here is a SUMMARY! The goal with this project: 1. Make docs contributions easier than any wiki 2. Make viewing & reading better than the current docs 3. Adding docs-support for external frameworks 4. Make searching and browsing easier than current docs 5. Keeping an up-to-date list of frameworks, modules and code-snippets 6. Provide better tools for writing a tutorial or article than these forums 7. Let newcomers and yet-to-adopt users a more wonderful time * Hosted by Mark * Trusted community members will have edit-rights to specific sections and needs to approve new content so the correctness can be kept at world-class levels * Framework & Module owners are given full access to their own section of the site for their documentation needs Let me know what you think! Given above, is there a reason you would still prefer the current docs? > Regarding Git Git is great for discussing a source project with a simple wiki and issue-tracker. While it is possible to merge html code it is not simpler than a wiki (which proved to be to hard) from either an admin standpoint or contribution standpoint, plus the current docs are not that great to browse even if they where to have the best content in my opinion. |
| ||
| @Taiphoz, please tell me what my advantages are, 'cause I can't see them. |
| ||
| @Tibit: How will the export to HTML work? How will these docs integrate into an IDE? |
| ||
| As Kalakian posted, it is a pain to have to dig into the source every time you want to figure something out. So much time is wasted. With as good as the community is, I believe the docs would be up to speed in no time. If people that contributed to the Monkey code forum here would go through and take code that was relevant to certain concepts and have them inserted imagine how nice that would be. |
| ||
| There is two options online docs or offline docs. The IDE shows html pages. It should just be a matter of changing the url in TED & Jungle like Monkey used a Wiki before with online docs. Can't be simpler. - Downside to online approach is that the docs won't work offline. + Upside is that any changes, news and additions will be instantly visible to all Monkey programmers. - Offline docs might load a few millisecs faster + Online docs can use the power of google to search. + Online docs can directly link to other sites like this forum. I never work offline, but I respect if that would be a requirement. Even for offline there is options and solutions! ;) I have been experimenting with the export html thing, I'm using a plugin in Wordpress that outputs a zip with the site converted to several plain .html files (similar how the docs are now) but with the layout of the Wordpress theme. I do see a benefit in keeping the docs in a wordpress theme (like it looks now) since the docs can be easily structured with navigation, related pages, related tutorials, related code snippets, and such things. However the third option is to create a exporter (in monkey even) that can create custom docs in any layout we want, if for example we want the IDE docs to be different in layout but use the online content from each patch. |
| ||
| @Taiphoz, please tell me what my advantages are, 'cause I can't see them. You honestly cant see a benefit in having the docs for your engine instantly available to users of monkey, you cant see that if the docs for your engine are in the official docs it might and probably would encourage more people to use your engine, especially if it does something unique. Mate the advantages far outstrip any time costs, specially if you already have docs the time rquired to import them to those docs would be minimal. Sorry but if you cant see it past this then........... o.O |
| ||
| The idea is also the time to create & update docs, for example a module, will reduce since it's just a matter of going to the doc-website and clicking the edit button at the bottom of the page. MikeHart, sounds great that you have a tool to build docs! If you are willing to share we could use that to generate docs? I use a plugin in Wordpress to create several of pages at once, useful for example when I want a page per function. I had been thinking to use that to create/update pages from code & comments, but for almost each "command" I wanted an example and extra text. If your tool is simpler than wordpress I think we all should use and improve it instead. I'm all for finding the best solution. It is about solving a problem, I'm not a politician and I don't care that much "how" we solve it, only that we solve it :) How do you do when you write docs? How does the generation work? Can you add formatted, syntax higlighted source into the docs and html5/flash examples easily? Any other things that might be smoother, easier? I would not be offended if you voice your mind, I would appreciate any feedback. The worst possible thing that can happen is that these docs become official and then we have people that feel they lost out because we did not hear them now. |
| ||
| I'v added a youtube plugin to the site and a video tutorials section which is in draft form just waiting to hear back from the video author before I make it public. |
| ||
| @Tibit: If you know how source code documentation works with Jungle IDE, then you can imagine how my tool works. It has a few extras but it isn't as easy to use as a wordprocessor. It parses the source code and with the help of some kind of markup tags, it creates html files from it. You can add anything via html code. But what you want to archive is better doable in a cms tool or something like you want to use. You want to be able to document it like in a wordprocessor. My tool doesn't help you here. Btw. what made you choose a domain name like this for a monkey related theme? And who chooses and decides who these "well respected" mods are? What is their qualification? You are closing a door on some contributers right there. That gives a bad taste. I would also list things in alphabetical order to prevent that people think you favor one thing or the other. Imho you also need to create style and formating rules/guides so contributers know HOW they have to add things. A consistant style is mandatory for a site like this. And people would need to monitor Monkey closely to discover any changes in it and change docs on this side accordingly. Anyway, good luck with your project. I hope for you that it takes off and is not dead right after the start like many/all blitz related community driven projects here. Are you contributing as well? @Taiphoz: Your points would be only valid if 1) i try to get as many users to use fE as possible. 2) i have would not have any documentation shipping with fE at all. 3) i stupidly hope that fE and this doc side would actually ship with Monkey one day. These are 3 times no for me. My only motivation for fE is that it supports my book and my dev hobby. That is all. But... i stop here. You know what is best for me anyway, i should just accept it. Lol |
| ||
| yeah your right, of course you are, it was incredibly silly of me to assume that after spending all the time writing a book and creating a game framework to go with it that you would actually want lots of people reading it, and using the framework. so sorry! |
| ||
| Its ok Paul. No hard feelings from my side here. I can see why you thought like that. But people have different opinions. But i think this page deserves a chance. And I think that the domain name does not fit but that was Tibits decision, so it be. I had a good nights sleep and i am in a good mood. So Tibit, how are people suppose to contribute to the side? Does someone already does it? I saw the entry for Diddy there last night but that should not stay like that, or? Just targeting to external pages defeats the goals of this project. Let me know when you have the style/format rules ready and i will add my stuff. |
| ||
| i agree the name "gamecrater" is a little obtuse to coincide with a programming language documentation site. i'd recommend gamecrater.com/monkey/ i don't want to discourage anyone, though, technical documentation is a tough job. doesn't pay well either. does wordpress incorporate a wiki style at all? last year, i was trying to get the wikibook for monkey going. i thought it was pretty good, but no one used it. http://en.wikibooks.org/wiki/Monkey/Language/Lists feel free to use whatever from there. |
| ||
| That wikibook looks promising. Is there an index page? Online docs really require an index page. |
| ||
| I think the domain name was simply something he had at hand or thought up on the spur of the moment, lets not forget that his hope is that mark will take the whole site off his hands and host it so the domain would of course then change to either be hosted here on monkey coder or another domain with a name to fit the content. got the go from Invaderjim and I'v already got one of his videos in the video tutorial page that I setup, if anyone else has youtube tutorial videos please let me know and I will be more than happy to add it to the list. http://gamecrater.net/?page_id=424 |
| ||
| I thought the wikibook option was good and the reasons that didn't go anywhere seem still extant. I'm generally uninterested in putting effort into products that are ignored or discarded on whims. Right now there's no convincing BRL entity that is supporting a community documentation drive or a standalone open-source product that enables a standalone community to do the same. I agree that Monkey could do with better docs but I'm not about to spend time creating them for free outside of any BRL effort. |
| ||
| I actually agree with muddy here, while this project has my full support, I would love to see an official reply from mark, even if its just to say "yes I might support this if it gains ground and has beeter docs that the official ones" or something.. just something to show us that putting in some hard graft will not be a waste. we all know far to well this community is not large enough to support an unsupported external docs system, as is evident from the other attempts we really need official backing here. |
| ||
| I have made a doc generator for the Ignition framework. It works by getting source code remarks and combining other docs. This saves me a lot of time after an update by simply rebuilding the docs. A WIP can be found here: http://www.docs.playniax.com/ I have no experience with wordpress so my question is can I import it somehow or what would you recommend? |
| ||
| First, this site was only a quick mockup I made. This domain should not be used. It was a domain I had lying around haha, I should have said something about it, sorry! If Mark does not want to host it at http://www.monkeycoder.co.nz/Docs/ then we register a domain like learnmonkeycode.com I did this mockup gamecrater.net because I rather show people what I mean than just talk about it. gamecrater.com shows my earlier mockup. Do any of you think WikiBooks has a better layout or usability? Please explain since whatever it is I think it is very possible it can be done in Wordpress even better. I had a wiki theme installed that I bought for this project, but I'm not even using it because I thought I could do even better with a professional theme, I can switch it to show you guys, looks like a nicely formatted wiki then :) Navigation on each page can be customized however the author wants. This is very powerful for framrwork authors since you can have it structured any way you want. The diddy part I just pasted something from their google code, it was just meant as a test and I know it is crap it is not supposed to be like that. The frameworks I selected was because I browsed to the /User Modules/ forum and added the first I saw and knew about. Please read nothing into that. I'm pro equality. So how are you accepted as a "featured" framework? At least one person. The author themselves or a community user. I will probably myself go trough the big onces (so please tell me which) if this project rolls and add/copy their docs even if the original author don't, given their permission ofc. There will be more modules, tools, frameworks than can fit in a menu of course - the idea is to once that happen sort them into categories. I think it can be solved in a way that makes everyone happy. @ Playniax, awesome I'll take a look. Whatever the case is, one can always copy-paste raw html code into Wordpress, just need to make sure the formatting is top. I had to add syntax highlighting to code in the monkey docs by selecting the area and clicking a button. What would be really nice is to have a API-Section that we can "erase" and "upload" to. There is probably an wordpress plugin for that. I think this can be a process that should take no more than 5min for each framework docs update. |
| ||
| I appreciate the great feedback and this discussion. I feel like we have already ironed out many questions and issues. Just wanted to say that :) And of course I will contribute to the site myself. I originally wanted this for my own framework back in the ALPHA, then I built gamecrater.com however now I'm doing it because I'd rather spend time having nice docs for the frameworks I use in one place (if only for myself) than having to do so much searching and testing and reading source code. And I'm hoping to help N00dle with docs for his framework. Usually all that it takes to get a feature going from a framework is knowing what it does and how I'm supposed to use it + a few lines of code. I'm prepared to spend quite some time now in order to save time for me and people I work with, and the rest of the community for all future. |
| ||
| EDIT - Changed the Theme to Wiki. |
| ||
| This domain should not be used. It was a domain I had lying around haha, I should have said something about it, sorry! ah, gotcha. you may want to mention this at the top, as it will be lost in the thread. |
| ||
| (Note: I'm assuming Tibit is talking about what is effectively a 'wiki' here...) I can't help feeling that 'web-based' docs aren't a great idea, and that local, 'source-based' docs are a better way to go - with docs either in separate files (as I've done), or in code (as bmx/Ziggy/MikeHart have done), and extracted to generate html, ala doxygen (which I did look it, but things got sticky due to the fact Monkey wasn't a supported language). It is much easier to edit source-based docs, and the fact is that the author of the docs will be making 90% of the edits anyway so having docs instantly available to everyone isn't IMO that useful. If the author of something wants to make their docs publicly editable, they can host them on github or similar (if they're not already) and changes can be merged with blitz-research/monkey at the same time as the actual module code. This is, I think, how 99% of real-world projects out there probably work? It also allows 3rd party authors who don't have stuff in the BRL repos the ability to create their own, private docs. There's also the question of accuracy and consistency. If a web-based docs system does happen, I would definitely like to see some kind of 'editor approval' feature in there to prevent against wrong/misleading/unreadable stuff being posted. I don't want to be constantly monitoring recent edits - I want to be leisurely selecting future ones! All that said, if someone comes up with something that works and gets widely accepted/adopted, I'd be happy to host it here, as long as SiH agrees (since he'd be the one dealing with the web stuff and he only has so much time to devote to the site). I'd be reluctant to host anything until it was at least as comprehensive as the current docs though, as I don't want to host something half-done that ends up getting abandoned. |
| ||
| My suggestion for documentation, and particularly Monkey that has most parts Open Sourced is to get specific software designed for these tasks: and the best are Confluence and JIRA. It's simply the best wiki/colaboration software used by AAA companies, JIRA as Agile tool is the best out there. Among the best online editor and Addons, it has what Mark ask. Editor approval, groups. Well, it's a software written specifically for documentation, teams, and it integrates with development tools (JIRA as Agile, BitBucket for revisions, etc). While a 10 user license costs $10 (for charity), it costs literally thousands of dollar a year, BUT open sourced project can get a license for FREE. My suggestion is to contact Atlassian and get a free license of these tools. It's proven software, very reliable and professional. It also can help coders to set up specific sprints, review code, test, integrate Bitbucket/GitHub for new versions and organize all work on a specific platform. You can get info in www.atlassian.com. BTW, I don't work for atlassian.com although I use extensively all their tools with joy :) Amando |
| ||
| > BUT open sourced project can get a license for FREE. Alas, this would mean no 'common' doc system for Mojo, or other 'closed' 3rd party projects like ignition. I still think bmx had it basically right - a built-in 'docmaker' that rebuilds docs from source. This eliminates all sorts of problems like wild edits, versioning etc, and you get the docs for *exactly* the modules you have installed. Docs are quick and easy to edit, with no faffing around with dodgy custom online 'richedits' or waiting for the modem to reboot (hey, it's NZ!). Yes, to modify docs you have to fork the github repos, but overall it just seems like there's less hassle or potential for drama doing it the 'makedocs' way again. As for the 'look' of the Monkey docs, if anyone feels they can do better please take a look at the src/george/page_template.html file and have a play. It's based on the python wiki system I played around with a while back, and is highly configurable. The only thing it really enforces is the 'page per scope' format (which I MUCH prefer to 'page per decl' - easier to get around and makes it absolutely clear where everything lives) but that could be changed if everyone prefers 'page per decl' or 'page per arbitrary category' or something else. Personally, I don't think george is far off being useful. I'd like to add the ability to trawl modules for .monkeydoc files (and .monkey files themselves for 'in source' docs), clean up the simple markdown' system it uses (you can always resort to in-doc html anyway) and build a better set of wrapper (ie: non-module/decl) docs. |
| ||
| well looks like that's that idea shot out the water, thanks for your comments mark, I don't agree at all but at least we know where you stand. If your wish is to stay with the system you have now which is single files, then may I suggest using something like Jungles docs, and how it creates them, with the addition that you use templates and tags for placing information, this would allow for doc theme's to be created by individuals which could then be shared which will at least improve the look of the docs. As for their content, I fear were destined to be stuck with shit documentation and next to ZERO example code unless you set aside some time and really focus on bringing them upto scratch, because at the moment they suck balls. |
| ||
| This is how I view it. Docs is a term we use for more than one thing. 1. We the API a As a programmer you want to know the name, parameters and their types of each method/function b You want to know the contract of a method/function, if is is non obvious c You want additional info about input/output of method/function, if is is non obvious 2. We have intro guides to a concept - tutorials,articles,references a When looking into a NEW concept as a programmer it is nice to have a guide that explains the common use b You want examples of the usage of code c You want an index with the names of Classes, Interfaces, Functions, Consts 1. API - Solution? It should be obvious that this information should exist where it is needed --> In The Editor <-- Having generated lists with html pages is just a hassle and avoidance for not solving the problem the way is *should* be solved. Those looking for a solution to 1 can simply buy JungleIDE and it solves a, but only sometimes b & c. The first reason JungleIDE does not solve b,c is because you only get the comment IF the author used wrote 'summary: which ofc most don't. If there where an international official Monkey standard to embed API-docs in code (a tag, pre-processor thing, or so) then any editor can simply use that standard and probably more modules authors will start to use b,c - however most likely most won't, the only solution to this is to allow the community to help adding these, here git-branching might be the solution. An API without a guide or index (see below) is often of little to no value. An API is rarely enough but can be if b & c are provided. 2. Guides - Solution? This information can exist anywhere. Forum, web, offline, inside example code, git hub, wiki and more... The key here is structure. You want categories and indexes so the user can find what is relevant and have an easier time browsing. Non intuitive structure equals more people not finding information and call out "lacking!" even if information exists. Non existing content results in extra time and effort in searching for answers, going to forums and waiting for a response. General Improvements * Being able to connect 1 & 2 allows for even more powerful docs * You want API & Guides for each module/part-of-framework you use * Going to the source-code to get 1 & 2 is time consuming and often error-prone * An index with user made modules & frameworks allows users to actually know they exist and what they do & if they work with latest version * An index with guides * These indexes are structured in intuitive categories (very important!) Guides Improvements * Embedding or linking code * Embedding or linking videos * Embedding or linking other Guides * Embedding or linking other Modules * Formatting tools for text * A way for users to comment on the guides * A way for users to submit their own guides * Having guides searchable (preferably using google-powered search) * OnHover Class links to guide * OnHover module links to guide API Improvements * Generate & Update from Code * Usable both for official and user made modules * Add b & c info * link to related guide * link to a usage example (BlitzBasic docs did this and it was BRILLIANT!) * link to related commands * OnHover Function/Method shows API reference * OnTyping Function/Method call shows parameter data from API Final thoughts * Wordpress online docs is not the best way to solve the API. It is actually quite bad for this. Offline docs is probably worse froma user perspective but better from a author perspective (close to code). * Wordpress online docs solves everything except the OnHover/OnTyped display * Generated docs CAN solve all API parts * Embedding a code example to each function/method is probably the best value for time solution no matter what platform is used * Because it is monkey I think the docs should support both OOP-Based & Function-Based API's * The API should be in control of the one who programmed it * The API should be close to code, or it might get "out of sync" * The API needs little to no contribution from a community, except for spotting actual errors Creating a great Doc-Generation system would be enough, no doubt. I'm just saying we already have a great system working. And they can both work together - API section updates from offline generated docs while Guides & Indexes section lives online and is converted to offline. |
| ||
| > well looks like that's that idea shot out the water, thanks for your comments mark, I don't agree at all but at least we know where you stand. I haven't 'shot down' anything - all I said was that I preferred 'source docs' (and why) but that if someone comes up with some kind of online 'mega docs' solution that works and is it least as comprehensive/useful as the current docs, I'd be willing to host it, resources permitted. Not sure what you were expecting me to say, but I think that's reasonable. > Wordpress online docs is not the best way to solve the API. It is actually quite bad for this. Offline docs is probably worse froma user perspective but better from a author perspective (close to code). Well, from a 'user' perspective it doesn't really matter does it? For users, docs are docs and it doesn't matter how they came into being. Or are you talking about '3rd party doc editors'? Or whether docs are online or local? In which case, as a user, I generally prefer local. > Wordpress online docs solves everything except the OnHover/OnTyped display But, as you've pointed out above, is inconvenient for API Docs? > * Generated docs CAN solve all API parts Yes, although in a somewhat 'rigid' way. You can ALWAYS get better results hand crafting anything vs automation, but I believe this approach is fraught with problems, which is probably what I'm really getting at... > * Embedding a code example to each function/method is probably the best value for time solution no matter what platform is used Not sure what you mean by 'best value for time solution' here...but another thing bmx makedocs did that I miss was allow people to put an 'examples' dir in their modules that contained runnable example code files that got merged with the docs. This way, the user can both view examples in the help system, and run them directly without having to copy/paste. Github would allow for community contributions this way. > * Because it is monkey I think the docs should support both OOP-Based & Function-Based API's Yes. > * The API should be in control of the one who programmed it Yes, an API author should somehow have some sort of editorial control over the API docs. > * The API should be close to code, or it might get "out of sync" Yes. > * The API needs little to no contribution from a community, except for spotting actual errors Well...not sure all Monkey users would agree. > Creating a great Doc-Generation system would be enough, no doubt. I'm just saying we already have a great system working. I have no idea what you mean here. Yes, creating a great doc-generation system would be enough! But I was unaware we already had a great system working...that's not the feedback I'm getting! Or are you saying you've already solved all these issues? > And they can both work together - API section updates from offline generated docs while Guides & Indexes section lives online and is converted to offline. I *sort of* agree. For module/framework guides, I'd still prefer to work on them locally in my editor of choice, and have them 'attached' to the code to eliminate versioning/editing issues. But then perhaps that technically makes them API docs, so not what you're talking about. For more general 3rd party tutorial style stuff, it doesn't matter as much. Such stuff could theoretically live in a 'docs/misc' dir in the monkey repos and be built with the API docs, keeping everything source based and in sync etc. But perhaps it would encourage more people to write such guides if there was a simpler online interface than Github? To sum up, if I'm reading you correctly you're talking about source based docs for API/decls, and web based docs for tutorials/guides - correct? Wont merging the 2 (esp. links) be a reasonably complex problem? |
| ||
| IMO, a good example is the blitz3d online docs. the API is authored, perhaps auto-generated, but community comments add examples and ask questions for clarification. In defense of those who want more Monkey documentation, the current monkey docs have very little code snippets attached. I think BlitzMax was a little better at this. An example I see often: if a user wants to know how to insert a new Node in a List, most users use search in the forums, but part of that problem is guessing the right search terms. |
| ||
| Yeah you mostly got me right :) By user I mean programmer; the viewer. Ease of searching, navigation and reading. API docs as I call it or source code examples is not what I think people want when they say "I want better docs". I think they want what I call guides. That is my point :) The easiest and simplest form of a guide is API + CodeSnippet. Quick to write for author, quite good for user. API docs already exists if you have JungleIDE, just start typing a function and they appear. An official #DocsStart #DocsEnd comment tag would be a wish. Guides, tutorials, samples or having code snippets next to the API is what I find lacking, and I'm not sure that it is solved by improving the API docs, but I think it can be solved *forever* in this great community by making the step to contribution lower. Framework & module creators are prime contributes, so I wanted to give something of great value back to them - a doc-system they can use and a place to be seen/searched. I think API docs are a remnant from ancient times before the invention of intellisense & modern IDEs. Take my spec-library as a "real" example. If I where to use Wordpress this is my process: 1. Add it as a page under the Modules/Debugging/mSpec 2. I create these sub-pages: * What is mSpec? * Download mSpec * mSpec Basics * Managing Multiple Specs * Specs Tips & Trix * Examples - Test a Tank - Test a Server 3. I'll create a menu with these pages 4. I'll add the menu to the left-nav of all those pages 5. Add content to each page No API is even needed and any beginner can get started in minutes. No need to browse source or examples. Here is the generated API docs: http://gamecrater.net/modules/mspec/ Maybe a bad example, but take a huge framework like ignition? What if they had a guide for GUI, one for setting up Screens, one for Camera, one for mapeditor - one guide for each major use case. That is what I want. That is what I think most users want. Examples are better than nothing, but it is not what I *really* want. By having a working system I meant Wordpress :) I think it solves the "guide" part in a very useful way seen from a user/reader/viewer, not because of how the text was created but because of nice layout, nice structure, great navigation, google site search and global index plus administration and community features. Combining the 2 in the way that generated API docs are uploaded as read-only docs should be simple, already have a plugin doing this from html files, just needs some tweaking. Linked code examples have one big benefit I like a lot which is that the doc generator can compile the examples and make sure they all still compile. |
| ||
| My 2 cents... I like Javadocs, comments within the code which an output can be generated from it - Its worked for Sun/Oracle it can work for Monkey :) |
| ||
| > API docs as I call it or source code examples is not what I think people want when they say "I want better docs". I think they want what I call guides. That is my point :) Ah, OK. Still, the general impression I'm getting is that source code examples are the biggest problem right now. But I'm still a bit confused - are you talking about a purely web based approach, or a web based/source based combo? In which case, how do source docs get 'converted' to web docs? Would a 'makedocs' app have to do HTTP POSTS or something? You were making noises several posts ago about source based API docs being a good thing, but your above example seems to be purely web based. |
| ||
| I find source based docs nice, but ziggy, mikeheart, playniax has all solved that problem? I mean API generation on the offline side, but these would be quite basic docs I have assumed? The point I wanted to make was that having an API is the trivial part of the docs. The meat and quality lies in the explanatory texts that those does (usually) not contain. Now that part can be online and/or offline, both having pros & cons. However I'm suggesting that maybe the pro's are stacked in favor of an more elaborate community administrated system? One of those arguments being that "guides" is what the users wants. So to get the best of both worlds one solution would be to build an importer for source-docs (official, playniax, Mikeharts, ziggys, and possible others). However all text written in a source-doc will need to be more or less "read-only" on the Wordpress side of things since it will be "replaced" each update/doc-rebuild. But those two approaches combined sounds like a killer solution. What I think is not a good idea is to have two parallel docs, which are up-to-date in different ways - I think the user should have one official source, linked from the IDE and this site. |
| ||
| > I find source based docs nice, but ziggy, mikeheart, playniax has all solved that problem? I mean API generation on the offline side, but these would be quite basic docs I have assumed? I was under the impression that your stub pages for playniax etc. would end up containing API docs too, as your last example for mSpec did. But they wont? Your site will just contain 'guides' for playniax? Or do you intend to import the offline API docs somehow? How? Or will playniax be expected to use the web system instead of source docs? Will they be OK with that? > The point I wanted to make was that having an API is the trivial part of the docs. The meat and quality lies in the explanatory texts that those does (usually) not contain. Perhaps this is where we really disagree - IMO, the 'meat' of the docs *should* be in the API docs. Guides/tutorials are great for getting started, but once you're up and running it's the API docs you spend most of your time in. For example: http://doc.qt.digia.com/4.6/qmainwindow.html (Make sure to click on the 'More...' link near top for detailed description - is this what you mean by 'Guide'?). Not the prettiest (the offline version looks better), but this page has pretty much everything you'll ever need to know about QMainWindow in it. It also has incredibly convenient 'jumping off' points in it via the 'type links' (ie: every class/type on the page in the decl docs link to it's own docs - current monkey docs do too) that mean I never really have to leave the API docs. This is most certainly not a tutorial (or guide, by my definition anyway) - it's the hardcore nitty gritty stuff that you *need* to know once you're 'off the ground' with Qt, and is the sort of stuff that IMO needs to be written/maintained by the Qt devs as it's vital it's accurate and up to date. It's this kind of detail (and examples apparently, despite all those bananas!) that I think Monkey lacks. I guess (maybe?) what you're effectively talking about is moving the 'detailed description' sections from the API docs to a separate page on a website. And yes, that has some definite advantages in terms of allowing the community to make contributions as opposed to Githubm although it does split up the docs considerably and introduce versioning/moderating issues. But as long as it's *only* the 'detailed descriptions' I have to worry about dealing with online (and not the decls), I'm less opposed to the idea. Perhaps we just have different definitions of API docs...! |
| ||
| Heck if its any help i could possibly code a docs creator that goes through the mods directory and parses all the .monkey files for #rem .. #end statements looking for doc keywords, the resulting docs would be put into the monkey help folder (after serious testing) i would make them simple HTML code so its quick to load and everyone has access to them locally. Here in the uk online docs are a pain as quite often in the evenings the internet crawls OR goes down completely whih makes online docs useless. Edit: another better idea as Mark suggested is seperate .monkeydocs files for each .monkey file, this would mean all that is required is to find the files and parse them creating output HTML for the docs. In the files we could have the standard tags [i],[b],[u] etc all ended with the [/..] stuff, however we could also add [html] so people could add stuff thats put straight into the docs. I could start work on this as soon as i get back, it will be a nice challenge and a welcome break from rope physics and star system creation :) |
| ||
| Or the three of us (Ziggy, Playniax, me) that have already created such a tool could modify it, to work with a still to be created standard doc format, and release it for all. Or we use George, modify it to take care of all the needs and then use that. By releasing George, BRL kinda has already set a standard. :-) |
| ||
| @Mark, what made you not go the BMX doc route for monkey. It seems everyone was happy with it. |
| ||
| I think if a tool already exists it could be modified to have code tags for example source and maybe other tags for links or youtube if required then it would be brilliant and the docs could end up as a definitive help resource instead of a pointer to 'go to the forums and search'. Iirc that was the problem with blitzmax's docs they werent comprehensive enough. |
| ||
| With any tool/website, the docs are only as good as the author will put effort into them. |
| ||
| Yeah this is why i would do a open source approach meaning once its completed thats it :) |
| ||
| Hi guys, I have always liked the BMX doc generation approach. I have made my own tool for this based on this idea. Every time I expand the framework I can update the docs by just running some scripts made in BlitzMax. The only thing it does not support is the F1 key but it’s not a big problem for now. IMO a tool like that is enough and could come from either Mark or 3rd party and then stick by it. I know Mark changed his mind about the BlitzMax doc system but I think it worked really well. For me the community does not do such a bad job helping other people with examples and all but for the less experienced programmers the official docs can be a little bit limited. I am not sure this can be solved by better docs but more tutorials about programming techniques and I don’t think that would be Marks job. The Playniax framework comes with a lot of examples and in source remarks but I noticed that people are really happy with the tutorials. I am going to continue this on this path but I think Mark is saying that this is not the same as API docs and I agree if that is the case. But the bottom line I think is content and a tool to easily maintain it, not where or who is hosting it and online or offline. I have put the docs of Ignition online just for people who are interested in buying it but I prefer the docs to be offline because of running demo’s from the IDE/TED. Just my 2 cents :) |
| ||
| The Playniax framework comes with a lot of examples and in source remarks but I noticed that people are really happy with the tutorials. I agree very much, not just for myself but also a lot of programmers I have worked with.and thanks for sharing your views, would you be even a little interested in having the tutorials/api online? Or do you see the downside to big? |
| ||
| With any tool/website, the docs are only as good as the author will put effort into them. I think this is at the core of it! :) In the QT Docs (it's C++ which is known to lack IDE support) so it needs the "API" printed. They call it Detailed Description & Member Function Documentation. I would not call it a guide. Having that I would feel lost! I have no idea what to do, best practices. But it might be what I need if I had a lot of previous experience in QT. However the "more" section that is maybe not a guide, but it is still quality "meat" information that could be enough. What it lacks is explanation of the concepts & context. Function Documentation imo should hold about this much information: Above: This is great because it gives abstract explanation in text plus a practical example in a context. If this was what API docs was about then an online doc version would be stellar. Also I understand that it feels good to keep docs inline with the code, I feel it too! My main reason for being pro-generated docs was that I considered me making an API change and then the docs gets out of sync. Could be a pain! However now that I have been thinking about it - it is not rare the API changes? If I have breaking changes then do I really just want to regenerate the docs and hide that fact? If I have a user base I need to let them know anyway! And change ALL samples using it! Is not the "click publish" idea just an attractive illusion? Now I have come to think generated docs is actual not useful at all compared to an online system. I feel like I have seriously considered both sides and the benefits far outweighs the risks from my point of view. * I fear it feels good for authors to have docs generated - it feels like something for nothing * I fear it misses the point about good docs, still requires the same effort (see QT example above) * I fear it encourage not having "guides" & samples * I fear it make the step to contribution higher & not as easy to ask questions to the author about the docs * I fear it discourage adding example code to each function * I fear it will be QT docs at the very best * I fear it will mean low-quality docs for not only Monkey but most Frameworks and modules * I fear I won't be using them that much, because looking at sample code will still give more "meat" Question still remains how online docs are used in the IDE. A super simple #Docs tag & #Parameter tag is still desirable. @The use case "I don't want to be internet connection dependent" - then we solve it by "saving" the online docs into git each update. Have a link in the IDE that say [use OfflineDocs]. |
| ||
| @Tibit: I think you made your decision, so make it official and open the site for real. |
| ||
| Personally i still think the blitz3d docs are second to none, they have examples for almost every command and are easy to navigate and use. |
| ||
| Why don't the various Framework docs work with the F1 key? |
| ||
| After seeing github do such prettiness with monkey source- http://github.com/blitz-research/monkey/blob/master/bananas/mak/firepaint/firepaint.monkey and playing with the wiki, I think the next step is to be able to link pages in docs from wiki. |
| ||
| so make it official and open the site for real I think you are right :) |
| ||
| Why don't the various Framework docs work with the F1 key? TED or a different editor? There is a index.txt file in Monkeys docs folder that needs entries for them in it. Just an hour ago I have finished this for my next release. My doc creator will now create also an index.txt file and another tool will patch TED's index.txt. So with a press of F1, you will get now context sensitive help in TED for fantomEngine with the next release. |
| ||
| I've just been playing around with George to make it little easier to change the look and feel of the docs. https://docs.google.com/file/d/0B1fT3tMIhbMPTUVQV3F4dXpvNVU/edit?usp=sharing I've shifted the css from the html to an external file, you can just change theme.css to suit your needs. Also implemented google-code-prettify with simple monkey highlighting (also theme-able). I agree with Mark in that automatic document generation is a good thing, it makes managing the docs much easier since you can just regenerate if you make a change and when you do look at the source, there's a comment as a matter of requirement that gives you info on the function/class/method you're looking at. Although docs that a user can contribute to would be useful to provide further discussion/examples on each item. Perhaps george can have a way of generating a link to the online doc location wherever that may be? |
| ||
| Perhaps george can have a way of generating a link to the online doc location wherever that may be? This is exactly the conclusion I arrived at too. I'll use GameCrater.net to build an place for guides, articles, tutorials and lists for modules, targets, FAQ & QA. A structure like this: Modules [Root] – Category – Module Name – Module’s Own Navigation Articles [Root] – Category – Article Name – Articles’s Own Navigation Tutorials [Root] – Category – Tutorial Name – Tutorial ’s Own Navigation FAQ [Root] – Category – Accordion Question List And the generated docs are more or less for the purpose of general reference & by the author while online are for more specific guidance & often by 3rd party. I think that will be the best of both worlds :) |
   |