Improving Dev Docs

(Dan Belcher) #1

Recently, when asked what we could do to improve plugin developers’ work, some requested that we improve our documentation. Our developer documentation can be improved. Here are some ideas…

  1. Automated API References. We need a good way to auto-generate the majority of the API Reference content to make sure it stays current. @stevebaer does this with the RhinoCommon references. @jesterKing has started doing this for the RDK C++ API. Both Nathan and I have been using Doxygen: check out the RDK and RhinoCommon docs for samples (sorry, these are not visible outside McNeel yet). There’s still more work to be done on formatting/styling (see 3 below), but it’s a decent start. We need to see if we can get Doxygen working with Rhino.Python and RhinoScript. Anyone know of other auto generation approaches we should consider?

  2. Canonical Location. Currently, developer documentation is located all. over. the. place. This is confusing to newcomers and experienced plugin developers alike. Having all the documentation in a single location reinforces the authority of the content…perhaps we could put this in some url scheme like: Over time, if 3rd-party developers feel this is the authoritative source, they will be more likely to offer corrections or criticism. I propose that the Wiki be used for Getting Started and Guides sections (or similar - see item 5 below) and for links to the API References. Sample Code could be stored on GitHub and serve as the source for samples auto-inserted into the References.

  3. Consistent formatting & nomenclature. Formatting and style can reinforce that the docs are authoritative. At the moment, our formatting varies widely. We should use an automated reference generator that allows us to apply the same styling across all the different API References (Doxygen supports css). The only deviations from this should be for conventions and nomenclature that are native to the language (namespaces in C# and C++, packages in python, etc).

  4. Not-Just-Robo-Docs. Most modern IDEs give good access to documentation - when available - via IntelliSense or Autocomplete. Given that fact, we should provide added value beyond just the automated references. Great API references also give examples, context, background and gotchas. We already have some of this content generated, but we need an automated way of merging it with the auto-generated API References where appropriate.

  5. Many Paths: Many good developer docs are split up into these 4 rough sections: Getting Started, Guides, Sample Code, and API References. The Getting Started sections are normally bootstrapping or tooling guides that offer extra support during the dabbling phase. The Guides sections are usually topic-specific guides and best-practices. The Sample Code sections are topical, didactic, illustrative, code samples (duh). Authoring these is lots of work, but we have loads of great sample code already.

  6. Cross-References. By this I mean cross-references between sections listed in 5. This is one of the harder ones to automate, keep current, and curate. Relevant cross-references usually need to be inserted (or at least curated) manually. Ideas on this?

  7. Links to source. If source is available on GitHub, directly linking to it from within the API References would be cool. I have seen docs that do this and it’s useful. This might be something we can automate with Doxygen or Python.

What’s missing? The first three seem like lower hanging fruit; the last four seem more difficult, but worth considering.

(Dan Belcher) #2

Here are some examples of developer documentation that may (or may not) serve as inspiration. In no particular order…

  • The MSDN Library: Some love it, some hate it…it is definitely
    comprehensive. For .NET code, it does a good job of mixing languages
    and giving examples…take a look at this sample.

  • The Python Docs: Python docs are Seriously Authoritative.
    Seriously Pythonic. The PEP system is pretty damn cool…and
    these are interleaved throughout other documentation, taking on a
    life of their own. Given the embarrassment of riches of
    documentation, I think Python does a good job of organization,
    clarity, and consistency.

  • The Xamarin Dev Docs: The Recipes section is worth a look.
    Xamarin also does a good job with their Guides: check out this
    . The API references are less than inspiring.
    Xamarin’s challenge is splitting up the platform-specific code from
    the cross-platform code.

  • The OS X & iOS Docs: The new Cocoa docs break down their
    individual api references by task, rather than just by constructors,
    properties and methods…check out this example. Also, note the
    (optional) mixing of Objective-C and Swift, akin to MSDN.

  • The Blender Python API: Offers great Overviews and
    Quickstart Guides in addition to the API references.
    Blender can actually expose the Python API from within the Blender
    interface, allowing you to hover over elements and get Python

  • The SketchUp Ruby API: Check out this example entry…do
    you think they are auto-generated from source? There’s a small set
    of Tutorials (Guides) and Getting Started docs.

What others should we look at?

(Steve Baer) #3

First off, thanks for writing this up Dan. I have had this on my “todo” list for a while and just kept putting it off because I knew it would be a lot of initial typing. I’m mentioning @dale and @andy since I think this is a better place to discuss this issue than having a goto meeting with each other.

Should we make this post publicly viewable in the “developer” category?

To me the biggest issue is the spreading of information all over the place and keeping that information up to date. I have been thinking about this for a while and I am very interested in researching github pages for the source of all SDK documentation.

This is a completely different path than the systems that we currently have in place, but what I like about it is:

  • All of the documentation is kept in git
  • If “outsiders” want to contribute, they can fork and send a pull request

The public mono-project web site was just converted to this system
Click on the “edit page on github” link on the above page. That is pretty slick.

I was thinking that we may be able to tune doxygen to produce output that we can insert into the above architecture.

(Steve Baer) #4

Of course this is a long term project; I’m not looking for yet another “quick fix” :smile:

(Dan Belcher) #5

Should we make this post publicly viewable in the “developer” category?

Yes, let’s do it. Done.

This looks like a fantastic spot to me. I’ll do some more reading, but first blush looks like it’s flexible enough to handle most things we could throw at it. I love the fact that it’s in git and readers/editors/perusers can do pull requests.

I was thinking that we may be able to tune doxygen to produce output that we can insert into the above architecture.

I’ll bet we can…Doxygen does support markdown generation too.

Good stuff.

Of course this is a long term project; I’m not looking for yet another “quick fix”

Definitely. This is a lot of work.

There are certainly still a lot of ?s…but it would be nice to have a test-bed like github pages so people can respond and contribute.

(Menno Deij - van Rijswijk) #6

:thumbsup: :thumbsup: :thumbsup: :thumbsup: :thumbsup:

(Nathan 'jesterKing' Letwory) #8 looks interesting. I haven’t used this before, so can’t say much yet about it. But I’m sure we’ll manage to find a way to keep docs in sync on both code and created doc sides. Probably utilising somehow the pull requests to make actual documentation changes to the sources.

I’m gradually working on my part of the documentation as part of my learning process while I work on RhinoCycles (Rhino plug-in for the Cycles renderer). I have noted what I’ve learned so far and it is slowly morphing into a primer doc into SDK/RDK/RhinoCommon.

RhinoCycles is coming along nicely, so I expect to have more time during autumn 2014 to put into actually writing some sane text for the primer, and on documentation in general.

(Dan Belcher) #9

We have begun work on

A Work-In-Progress, the site is aimed at addressing many of the issues “discoursed" above.

In short, is:

We are currently in the process of authoring, porting, and consolidating content. Entire SDKs are missing. The API section needs more work. The samples have yet to be sorted out, etc. That said…

Please take a look and tell us what you think. Better yet, help us build the site.