PROJECT: MonkeyDocs

Monkey Archive Forums/Monkey Discussion/PROJECT: MonkeyDocs

Tibit(Posted 2014) [#1]
After Marks Blog post I felt I wanted to contribute something I should have done a long time ago - improving the docs.

The idea is to both improve the docs for experienced users and for new users.

Here is a mockup:
http://www.truplo.com/monkeydocs/home.html

I have changed the layout, and worked a bit to hopefully optimize the navigation.

Ideas:
* Finish layout css and choose appropriate colors
* Add Guides where appropriate (mostly for beginners)
* Add Tutorials from the Tutorial Forum into "Guide" Section
* Do Something on the Community Module section
(A module tool/site would probably be the best solution)
* Improve API-Docs with code snippets
* Maybe organize the Samples by category
* Check that code in the docs abide to good coding practice

Any discussion, suggestions, comments are welcome!


nikoniko(Posted 2014) [#2]
Hmm, total right aligment? It seems unusable for me.

IMHO using Wiki like doc is preferred for readers and doc writers.


Tri|Ga|De(Posted 2014) [#3]
For me it just a white screen without content. On both Safari and Firefox.
I'm on Mac.


dragon(Posted 2014) [#4]
this is a mockup without content...
yes right align is unusable - and the structure is not user friendly


Nobuyuki(Posted 2014) [#5]
monkeydoc's output is fine if you ask me. You can already make a template and rebuild to suit your needs. What monkeydoc really needs is more extensive support for autogen on various things like keywords, precompiler directives, and function params.


Paul - Taiphoz(Posted 2014) [#6]
I actually love that slider effect but having it on the right seemed odd to me as well, having it on the left side might be better.

As for the Doc's themselves, I really wish we would adopt something like the PHP Docs, take just about every php function there is like this http://www.php.net/manual/en/function.stream-select.php and it clearly defines what it does, not only that it shows an example of its use and as if thats not good enough scroll down and you get countless user examples of its use and a varied number of methods and uses that are available with it.

If your going to overhaul the docs I hope you take a leaf out of PHP's book.


Tibit(Posted 2014) [#7]
If you see nothing then something has gone wrong. I used a jquery framework for the Navigation, maybe there is some issue there. Have only tested on Chrome and Internet Explorer on Windows7. Should be responsive and work on both mobile and desktop.

The slider is on both sides. Open the language Reference to see the intended use. The right side closes after click, while the left stays open - but only on pages that has page-navigation.

Maybe the right menu should be a "top-bar" menu instead? Other suggestions?

This is not changing the output of MonkeyDocs, this is the Core Documentation Template Layout - which content will be filled by MonkeyDocs genereated docs, guides, tutorials, getting started, language and target information and such, I understand if my poor naming of this thread caused confusion.

@nikpniko - What features that a wiki has would you like to see? Please open the language reference to see if that perhaps is closer to the layout you mean?

@Paul - Yes the goal is to add more content to the docs and add gaps such as parameter usage, and more samples - similar to the php docs you linked. Which part of the docs do you think we should start with?


John Galt(Posted 2014) [#8]
Just a white screen here, Firefox on MacOS Mavericks.


Nobuyuki(Posted 2014) [#9]
@Tibit : Please start with parameters! They seem to already be partially coded in the monkeydoc source, and were omitted for whatever reason. (Possibly Mark couldn't be bothered to document each and every parameter, when they're mostly straightforward to understand). If you check the metadata used to generate the docs, some parameters even already have what appear to be description placeholders.

my pet reference to go to is MSDN. The description pages are similar to php.net, but the way pages are organized are different. I like this way a lot, especially the sidebar since it allows you to traverse the class hierarchy rather easily. That's something you should consider if you're designing a menu system, how easy it can be used to do a task like that without having to look/click around a lot.
http://msdn.microsoft.com/en-us/library/system.io.filestream.read.aspx?cs-save-lang=1&cs-lang=vb#code-snippet-1


Paul - Taiphoz(Posted 2014) [#10]
Syntax Highlighting on the example codes is a must I think, it makes it easier to read code when its highlighted and there are a number of systems that do monkey already so should not be to hard for you to implement.


Tibit(Posted 2014) [#11]
Nobuyuki, great feedback! Yes I will look into adding all parameters - great simple thing to start with.

I hurried together the first prototype in hopes of getting feedback, appreciate all the replies I got, I apologise for it not working for many of you. I'll post an update soon.

Yes, syntaxhighlighting is a given :)