wiki and Gideros documentation

boriskey

Anyone who wants to contribute to wiki can now request accounts and will review and approve them
http://giderosmobile.com/DevCenter/index.php/Special:RequestAccount

Probably a good idea to open a new thread on this and discuss how documentation will be supported going forward. While some of us cannot contribute to open source code, we can help with documentation. And good and clear documentation is often a necessity to attract more followers.

My question is about wiki docs vs main gideros documentation site (I love its design btw!) - is there any way to contribute to main documentation site or wiki will the main place going forward?

Also I found that a lot of wiki pages are very outdated and main documentation site is more accurate and comprehensive.

totebo

Good questions.

ar2rsawseen

I would need to figure out how to give access to main docs, right now there is a small UI to modify it, but very ugly and probably not so comprehensive

But the difference between docs and wiki I think is quite obvious
Docs document all Classes and functions with examples
while wiki documents everything else, from tutorials, to stuff that does not fit anywhere else

boriskey

i saw quite a few overlaps actually - like deployment instructions and building custom player, docs for some addons also. I was struggling there a bit myself. Also "The Ultimate Guide to Gideros Studio" is good but very outdated and uses examples and description from old version of docs.

Is gideros documentation autogenerated for every class/method or it is a manual process? if it is a manual process, probably would be easier to keep this all in wiki?

I am not a huge wiki fan and it is ugly right now, but I think it would be good to have this in one place or at least remove overlaps. Especially if there is no way to modify documentation for other people.

I could also change docs a bit for iab and ads libs - there are things that I spent a lot of time on to investigate (granted not Gideros or libs related but iOS/Android related) but I could describe these pitfalls there so other developers would not spend time on these things and would need to read ios/android documentation.

Do not get me wrong, it is not bad right now but since the project is moving open source direction, I think this is one of the important things to cover early.

ar2rsawseen

Documentation was autogenerated at first and then modified and edited by hand, through web interface and is stored in db.

But one thing that could be done, is generate HTML docs and allow everyone on Github to edit HTML files and dump the db.

I really don't think storing class/methods info in wiki is really suitable, mostly because of UI, no collapsing, etc.

But if needed I probably can create a script to export it to wiki markdown

Other approach could be to generate xml or json docs sources and create a script to display web docs from these xml/json sources.

And then community could edit these sources (which would be much easier to edit than HTML)

totebo

I would also prefer to have the knowledge base and API in one easy-to-edit place. Have to say I'm also not a fan of wiki. Are there other better suited options? If not a one-wiki-to-rule-them-all is to prefer to me.

ar2rsawseen

Hmm, how about this one?

https://readme.io/

and they have a free plan for open source software

boriskey

@ar2rsawseen very interesting and promising project and this is exactly what I had in mind. I actually spent a couple hours another day trying to find something like this.

This is what I was looking for:

1) good looking and modern design - check!

2) intuitive and easy to use for people who do not want to mess with wiki or markdown check, check! and you still can use markdown if you want. I love their super easy editor.

3) predefined styles for comments/notes/warnings and code examples - check, check! What a nice idea to use drag-and-drop blocks! But I did not see Lua in a list of available languages

4) API for code documentation - check!

5) optimized not only to create code documentation, but also tutorials and articles - check! API docs and tutorials in one place finally

6) I did not expect this but it is a really nice feature - discussions and comments to documentation

So it looks like a very decent choice. I will be testing it some more later.

They did not say much though about limitations of open source version. Like they state there will be only one admin, it means only one person can approve edits. Will it be okay with you?

ar2rsawseen

Yes, but does not have one thin on my checklist, importing old docs in any format, that I could generate Or maybe I have not found an option yet to do so.

One account might be a problem, but there would also need to be someone who would review changes. so we can cross that bridge when we come to it

boriskey

hey you cannot have it all I am in IT for a long time and still looking for perfect tools

but this project you found is very close to a documentation tool that one might actually want to use and inspire to write more and more (at least I feel it). Documentation is a chore and everyone hate writing documentation and tool needs to make you want actually do this chore.

I think they mentioned they can use git markdown so if you can convert to git markdown first - maybe using pandoc? but this is not really my area of expertise. Hopefully someone else can chime in.