Can I help improve Documentation (and examples)

Developing Cinder
1

I’m new to the forum but I’ve been using Cinder on and off for about 6 months now in various projects. (I make interactive installations for a living.) My background in C++ is mostly using openFrameworks but I’ve also used Processing (Java) and in the last few years I have used web technologies (especially NodeJS) extensively.

The Cinder library is certainly powerful but personally I have found two areas of weakness (just my perspective, so feel free to disagree!):

(1) The documentation is quite terse, and in any case the search functionality is broken on the site which is endlessly annoying - I see a Pull Request for this has been open since May (https://github.com/cinder/Cinder/issues/1837). And I don’t see any obvious way to help improve/fix the documentation? Is it automatically generated?

(2) There are guides but very few examples in the documentation itself. I guess different developers have different styles but personally I love to work from examples that show how functions and classes are intended to be used, in a relevant context. The documentation for Processing is particularly good at this (take a look at any example, e.g. https://processing.org/reference/color_.html). Even most web development frameworks/libraries are much, much better at this sort of thing, providing examples alongside the reference detail or even “recipes” snippets that show how common use cases ought to be handled.

So in summary, I’d love to know:

  • Is there a way that the documentation can be made more open to community contribution, so that developers who are using the library every day can keep it up to date and more helpful, especially to newcomers?
  • Along the same lines, how can examples / “recipes” be incorporated into the documentation so that it is not only about a reference but also shows how things work in context?

Interested to know what others think. And, yes, I’m certainly volunteering myself to do whatever work may be involved.

4 Likes
2

Hi @anselan. Happy to hear that you’ve made your way to Cinder. Also, I’m excited to hear that someone is interested in working on the docs too. We came up with the system to generate in dynamically about 2 years ago and totally understand and agree with it’s limitations and annoying bugs.

To answer a few questions…

  1. Yes, the docs are automatically generated. In the docs directory of the cinder source, there’s a python script, called generateDocs.py that goes through an XML tag file that’s generated by Doxygen. It then pulls in all of the guides and supplemental HTML documentation files to create the website.
  2. We originally had in mind that we wanted to include samples in the docs themselves, a la processing, with perhaps some interactive 3D content. We never got to that, but yeah, that’d be awesome. We definitely should do that.
  3. The docs are open to community contribution as it is, but I understand how it’s not super straightforward to follow. You can get a start by running the docs locally. Follow these guides: https://libcinder.org/docs/guides/docs/building_docs.html and https://libcinder.org/docs/guides/docs/documenting_cinder.html
  4. There’s a way to include samples / recipes as it stands, but worth revisiting if there’s a better way. It’s done right now by creating the html file in the docs/htmlsrc/_docs/ directory and then defining where it should be injected via a custom tag. We did this for Logger (https://github.com/cinder/Cinder/blob/master/docs/htmlsrc/_docs/log/Logger.html).

Next steps as far as I’m concerned:

  • Get search and stupid bugs on current site fixed
  • Perhaps make a docs a submodule, which will make it easier to contribute for others like yourself
  • Revisit the docs generation script and see if there’s a better open source option that could assist with the process, which we originally researched, but found no great alternatives
  • Gather all feedback and feature requests and figure out the roadmap for V2

Let’s keep the conversation going.

3

I’m interested in contributing too :raised_hand_with_fingers_splayed:

4

Ah this sounds good. I’m going to have a look at the documentation system first, as you suggested, and see how easily (or not) it can be improved with the current setup.

5

I think it’d be so awesome if more folks got involved with the great system that @GKeps has gotten set up, it really has potential to make some nice docs but of course it takes time and Greg is just one person, with a full time job and family at that.

I think the basic idea is that people working on library code can document reference-like things in line, while guides and examples are worked on separately from that. We have many, many examples, and many of the replies you see on the forum when someone is asking for help is for one of us who knows the library well enough to link to a sample or guide - I think it’d be great if had this set up directly in the docs, similar to how Apple links relevant samples within their reference pages. I imagine that with some python magic, this could be managed outside of the inlined doxygen so as to keep clutter in header files at a minimum, if that is a concern.

The other low hanging fruit I see is that there are still a couple guides (like the images one) that are out of date and need to be updated due to API changes from when the guide was originally written until current day cinder. This would not only be a huge contribution, but be an avenue for getting used to working with the docs system.

Really happy to see more people in the community interested in docs! It’s one of those things that pays huge dividends, but is difficult to fit into our busy daily schedules.

cheers,
Rich

1 Like