New OpenFrameworks Website

#1

This past week at the OF contributor’s conference we had a series of discussions about overhauling the project website and bringing it into the modern era. As you can imagine this is no small task as it involves reorganizing the canon of information and resources that currently live on the site in addition to a significant UX, design and engineering effort. We started to outline what a new OF site could look like and @armonnaeini mocked up a quick interactive prototype to explore how it might work.

We’re still in the very early stages of exploration and are looking for folks excited to jump in and help us bring this effort to life. Over the next couple weeks we’ll be working on a road map to guide us towards launching a new OF website in the spring. If you have experience in web design or development, information architecture, interaction design, or program management we’d love to have your help! We’re going to host a google hangout in a couple weeks to share what came out of the OF contributor’s conference, bring everyone up to speed and plan next steps. The impact that a new site will have on OF can’t be overstated. If you’re interested in joining the hangout please add your name & location (for timezone purposes) here. Thanks!

12 Likes
#2

The site content could certainly use more detail and updating.

I hope there remains an easy-to-find compact text-based menu of the site content, and that it isn’t replaced by a huge vertical visual marketing exploration experience.

1 Like
#3

wow. I’ve been wanting a new reel for so long. but also a mobile friendly site.
better documentation would be really nice to have.

id love to help all I can. I do know some website stuff. mainly using Jekyll for all my site stuff, since its sexy & easy to use, but extendable

3 Likes
#4

really, maybe i’ve read the things just too quickly, but all the things you are trying to achieve could be achieved already with the current resources, by example by improving the ofBook

i really don’t understand how putting a mutilated version of the documentation in the official website could help anyone, if someone goes to search some function on the documentation it’s clearly not searching the most basic things anyone can memorize. But if we were heading toward that path, at this point oF shouldn’t have had transitioned to glm, that is really harder to manage than old trusty ofVec ( and broke lots of things ).

I always found oF very different from processing, in processing the learning is clearly highly hierarchical, there are lots of people learning it from much fewer people and many of the people that use it don’t contribute to it. Much less people use oF, but usually an higher amount of the user becames a contributor, so everyone pretty much learns from anyone and it 's nice

for me the modern era is about decentralizing, about avoiding to use github and hosting our own repos in a way that none of us has to be excluded, about static websites that don’t use cookies and don’t track you, maybe even with lower emissions, it would be very nice to go in that direction, instead it looks you people just wants to make a big effort to make things look simpler than they are

1 Like
#5

As one of the people who worked in the documentation group at the conference, I can give you some insight on our logic.

i really don’t understand how putting a mutilated version of the documentation in the official website could help anyone, if someone goes to search some function on the documentation it’s clearly not searching the most basic things anyone can memorize.

The current documentation is, quite frankly, dense and overwhelming. It’s hard to go to it and look for basic functions to get you started. As someone who’s still kind of greenhorn to oF, the documentation is the sole reason why I put off learning and using oF. I can say the same about most of my peers in undergrad. We mostly stuck with Processing because it was easy to pick up and get into its guts. I know that some professors are reluctant to teach oF because it’s hard for students to grasp it because the documentation isn’t friendly.

The documentation group thought that the easiest way to get people to use oF more was to clean up the documentation and create a list of functions a beginner will need. It gets their feet wet and makes the task of tackling the complete documentation less daunting.

in processing the learning is clearly highly hierarchical, there are lots of people learning it from much fewer people and many of the people that use it don’t contribute to it. Much less people use oF, but usually an higher amount of the user becames a contributor, so everyone pretty much learns from anyone and it 's nice

We want more people to use oF: it’s a solid library and a good tool for people who have been using Processing. I don’t see any downsides to making it easier for people to use oF if it doesn’t impede on experienced users.

2 Likes
#6

Nice work on the prototype @armonnaeini!

2 Likes
#7

It is like this because oF gives access to a lots more things than processing. A language reference is like a dictionary, it should be fully featured and easy to consult ( even offline, there is not easy offline reference at the moment, you should serve the site on your pc ). If you want to make a cheat sheet you can make it, but it cannot be The Reference for the library API in my opinion.

Also trimming it down will make things maybe easier at start but generate confusion later, as people won’t be aware of all the things that are already there.

A language reference is not the place where you learn a framework, you learn through lessons, tutorials and examples, learning a language from the reference would really be like learning a language from the dictionary, instead of taking lessons.

Also, much of what you are trying to do would be better achieved through improving tooling, as you can read on this article.
Even if would be hard for oF to reach that level of discoverability, a big improvement could be something like ofSketch, with the added functionality of integrated autocomplete (with reference) and livecoding with ofxLiveApp, so contribuiting to those projects would be much more useful than making the reference worst for everyone.

As stated, (in my opinion) you are impeding experienced users, middle users, basically everyone that is not a beginner.

PS: Sometimes they ask me to teach workshop on what i know, but usually they are always one day workshops so i always refuse, because i don’t believe that anyone could learn c++ in just one day.
I’d like more people to use oF, but if you make this effort to jump on the train of that kind of behavior, i don’t find that honest. But this is just a side note, i hope everyone here is not trying to sell out anything and is motivated by a pure desire of making things accessible.

1 Like
#8

a lot of the motivation for improving documentation comes from teaching, where students are quite often overwhelmed by the documentation which seems both massive and un-finished. We believe we need a simple view (such as what the OF cheat sheet provides) that hides some of the complexity of OF as well as the auto generated view. By simplifying the api for the minimal docs we can focus on making sure the documentation is complete and understandable.

I have taught OF for 10 years or so, for students who are just getting started with OF better documentation is a must and having both a simple and normal view to the docs will help. We will still keep the view to the documentation as is, in case you want to search and we will make it clear that there are other things to find / etc. The goal is not to hide anything but to provide a lens that makes learning OF less intimidating.

8 Likes
#9

ok, so i probably saw the documents in the wrong light, nice to know we’re heading in the same direction.

1 Like
#10

absolutely. great documentation is the gateway for everyone to learn from.
we need documentation that speaks to users that dont know programmer speak, as well as can still speak to current users…

3 Likes
#11

To ease the flow of both reading and updating documentation, could the docs not be added to OF main? For contributors it would remove a hurdle toward keeping the docs updated / in sync. I also find myself opening lots of web tabs, which isn’t possible if there’s no connection.

So perhaps appended to the header files as a comment w. flags for short version / long version. There could even be something for serving docs locally:

/openFrameworks/scripts/launchDocs.sh
or
/openFrameworks/apps/documentationServer

#12

Just seeing this now! Let me know if the hangout has already happened

#13

It would be great if it was easier to contribute to the documentation. I didn’t manage to make Nikola work in a reasonable amount of time. https://github.com/openframeworks/ofSite/issues/679

If I remember right, when it worked, building the docs was very slow, but maybe this was fixed? I’m used to https://gohugo.io where changes are updated live on a local server. I think Arturo mentioned that the slow part was parsing the source code to extract data from it. Maybe that can be optimized?

Just to point out that I wanted to contribute to the documentation, but I limited myself to small changes done in the GitHub website because it was not easy to build the docs locally.

Sorry if this is a bit on a tangent but I think it’s related to the documentation effort :slight_smile:

2 Likes
#14

The problem is that at the moment the documentation is integrating the docs created by doxygen with (in some cases) markdown files. This integration works through a python script. Moving away from a python based website generator means also taking care of this transition.

There is a channel called #documentation on Slack, the main topic at the moment is the “focused reference” https://docs.google.com/document/d/1GvJeS7UwM0BIxrGwu60xUXCGe6DRUSJlv30PQZcxfrA/edit
every person interested in improving the docs is always welcome :wink:

#15

ive been giving this some thought & wanted to at least say it before I fully forget it.

but in terms of learning, having more examples would be great. I think since I’ve been looking at processings own website. I love the examples they have. so many & all of them can be useful in some way.

whilst they have interactive ones which is great & shows why processing is a lovely thing to learn & even know. using emscription [I feel] would be too much with openFrameworks, since having less overflow & loading is best.
it still would be nice to have examples & code laid out that many can look at, maybe a .GIF or 2 to show the outcome. even have a source code download button that someone could plop in the projectGenerator & update for their system.

but if its open to others to contribute, it would be good to stick to certain aspects the examples are submitted. so you have a .GIF of 700x500 or images are set the same. it just then has a better flow if things are kept nice & looking good

3 Likes