I would like you to consider a problematic of 3D designers who find documentation and information of SDK for program Rhino and Grasshopper for experimental solutions or specific tools.
I’m talking here about 3D users who are not professional developers, just users who can open IDE, link the SDK and use it.
I’m not talking here about writing plugins like VisualArq or T-Spline. I’m talking here to playing with RH and GH programming in an easy way.
And I would like to propose to the voting community a minimal and simple help solution
Today, what we have?:
A good SDK in different languages,
Some good IDEs.
The Rhino Developer Docs site with:
A good place to start but for general purpose.
Some good code examples but without explanation like the Rhino Github samples repository
Some videos that may be more detailed.
In this case, english videos tutorials are very restrictive because a lot of people can read on forums or english documentations (with or not with automatic traductions tools), but listen and understand an english speaker is very most hard.
And the API references site that don’t contains more information than the intellisense of editor can give us
This forum and the old Grasshopper forum that probably contains all the information we need for development but drowning between a multitude of messages. In this case the tags and categories want to help us but with approximate and variable results according to the good writing of the author (title, tags)
All this is a good support, but if you exclude the restrictive case of English videos and information in the forum that drowning between a multitude of messages, understand the functionality of SDKs is not easy.
Also, in practice, we can open, the code editor, API references, the web page of the forum and juggle with them.
this approach is not practical and very long for 3d designers (especially for 3d designers because professional developers probably do not need to look for so much help).
Proposal to improve this:
All is in the title ! “Integrate forum and samples to the API reference”
Considerate the PHP manual, in my opinion, it’s the best documentation that exists.
I pass the aspects of this manual that are difficult to implement in Discourse, Sandcastle Help File Builder or Doxygen and I am interested in function pages. For exemple this page http://php.net/manual/fr/function.preg-match.php but others is same.
Traditionally we have function signature, short description, arguments description and the return type but with an official exemples/notes and contributing exemples/notes.
Everything is in one page: API, examples, help. I know that many professional 3D designers use two screens, in this case, a documentation / API similar to the PHP manual would be very powerful.
By analogy with the PHP manual, we have:
The traditional function signature, description,… is the Api references site
The official examples/notes are the Rhino Developer Docs site and the Github sample repository.
And the contribution examples/notes is this forum
So, how to integrate this in one page?
Discorde propose all we needs:
The discourse-solved plugins, https://github.com/discourse/discourse-solved
A voting plugin to trace the best answer, https://github.com/discourse/discourse-voting. same as the PHP manual or Stackoverflow
Some options to integrate an external URI, is useful for creating linked data between a post forum and an API function. for example https://github.com/danskdynamit/discourse-links-category. With this, you can imagine having for “Rhino Developer”, “Scripting”, “Grasshopper Developer” and “OpenNURBS” categories a new field where you can copy the URL of the API page related to the question.
on the API side:
And if you know the documentation generators, you know that all can integrate custom scripts and template.
With this, we can have on the API page all topics that are resolved, related to the function and order by the vote relevance response.
The integration of official codes samples can be done in the same way but I stop here the technical details.
It’s just to say: I looked for the relevance of my proposal, it’s very simple. I’m just a simple hacker and even me, i could do it. So efficent access to information is essential to engage users/coder and eliminate redundant topics. And above all, make development accessible under RH/GH…