estevancarlos

It seems like Cycling74 is making some website and documention fixes and/or changes. For example the wiki has now been removed. I'd like to throw out ideas of effective online documention I have seen.

I always appreciate great documention and learning resources especially since it's necessary for my full-time work. One example is the documention for the Python framework, Django - 

Some of that may be obvious but I hope the new website changes from Cycling74 opens the door for some new changes to online resources.

For the point of comparison, I'd like to show an example of poorer documention. The example is Drupal.

There are other problems with the Drupal documention but it's unfair to point it out because they're obvious problems and they're in the middle of a major documention update. However the problems I list above I believe are easy pitfalls people should avoid.

Screen Shot 2017-04-17 at 10.23.19 AM.png

I always appreciate great documention and learning resources especially since it's necessary for my full-time work. One example is the documention for the Python framework, Django - https://docs.djangoproject.com/en/1.11/

You're immediately introduced to the structure of the documentation. The first list of items links to specific, higher level, categories of the documention.

The documention is separated into categories relating to a person's needs: tutorials, topics, reference, how-tos (recipes). Another way to imagine this is that steps for creating  patches can be listed under tutorials. Topics can provide articles about narrower subjects within Max (Gen, OpenGL, DSP, Math). Reference is... reference. Then how-tos are instant examples relating to specific tasks that can be performed in Max.

The use of lists. This Django documention feels easy to read by providing thorough lists outlining the nature of itself. The "how-to" front page is a list - https://docs.djangoproject.com/en/1.11/howto/. The tutorial front page is also a list - https://docs.djangoproject.com/en/1.11/intro/ 

The title of pages are explanatory and describe a task that can be performed. Examples: "Writing custom django-admin commands", "Providing initial data for models", "Deploying static files", etc.

Some concepts are presented towards different categories of users. For example in web development, you have a separation of the user interface style and the business logic behind it. A portion of the Django documention on a specific subject provides links for "programmers" and different links for "designers". Chances are some concepts in Max can be presented towards different types of users.

Some pages don't properly link to one another or offer a logical progression. This introduction page doesn't guide the user to read anything else - https://www.drupal.org/docs/8/understanding-drupal/overview

The side menu does list many items but maybe needs more context like introductory text you find on the Django documentation. I suspect some of these items can be combined into logical groupings. As a long list it's not sure what to read next - https://www.drupal.org/docs/8/understanding-drupal

It seems like Cycling74 is making some website and documention fixes and/or changes. For example the wiki has now been removed. I'd like to 

one-of-my-favorite-examples-of-online-documentation

For the most part I think Cycling74's documention is good but I think they're missing structure with content that falls under "how-tos" and "topics". I think those are two areas that should be worked on.

One of my favorite examples of online documentation