Thinking of areas of views documentation that would've helped me to figure out how to make views handlers
Background: I had a hard time learning how to do this, and then was shown how by my co-worker. My internet searches, use of the Views 2 API and views pages on drupal.org were not sufficient. After learning how to build these I realized that nothing I found on the internet would have helped me put the pieces together.
Use case: I am a Drupal developer who had to build views plugins for work. I usually can figure out Drupal 'systems' that go a few levels deep in abstraction, but have a harder time with things that go many levels deep.
After learning how to do this, I can identify several documentation 'projects' for users like myself. The problem is complex enough that I need to make a plan about how to proceed.
Making this plan publicly since I know that I am not alone in having difficulty with this. I do not know the folks who contribute to views, but I heard that it is just Earl Miles & that is starting to change. My intention is not to expect one man (the views creator) to do all this work, but rather to guilt trip myself & all my friends into working on this.
document what the problem was & what i would've needed to know (what did my co-worker show me how to do that wasn't on the internet)
suggestion from webchick: put request for documentation in an issue queue (after i write up some notes)
this summer we may do a project involving making views handlers. teaching would cement this knowledge in my head. and i am very excited because they aren't actually that hard to do once you figure out where to look & which things are required. views handlers might make nice 'teaching projects' because they are very powerful.
look at advanced help. need to look more closely at that. I will see if it would've contained what i needed about this 'views glue' documentation. I usually skim/search through the module code & the views 2 api website, which i was assuming were the same thing.
there are 'views help files' somewhere that i can look at
describe 'views glue' -- maybe making an example views handler module with video & explanation of why you might want to do this.
Caveat:
I only barely understand views, so I am just getting started. I am in no ways an expert.
I think that in a few weeks at work I might have to do more views stuff, so I will get to work with views again. I will think about this and try to figure out how to document what I did.
Think & learn more about documenting things that are more abstract. But I do * think that figuring out how to document the more abstract stuff would help with the arguments about using OO in Drupal...cause now that I see how it works, I don't think it's all the language structure - more about how the community figures out how to talk about it. Maybe some people already are...but as someone new to this I can say that using the methods that worked for me before did *not work in this case.
Subjects to write about:
* 'why you would make a views handler'
* 'how views handlers can empower you'
* 'how to figure out how to build what you want to build' with views
* 'how to set up a views handler'
* what do people mean when they say 'views integration'
* how to 'make a views module'
* 'what is the difference between plugins, handlers' and other views-centric words.
Things to look for:
* what documentation already exists
* what documentation exists already on drupal.org and where is it lacking?
Handbook pages:
* make issue to improve views documentation (explaining for which kind of audience)
* have a 'views documentation' virtual sprint and invite others to participate
* library of screencasts (assuming they exist)
* example modules
* point to various resources & reviews of those resources (good tutorials, books, videos and stuff like that)
* make a list of contributed modules that have views integration (these modules have example code which will help people figure out which parts are supposed to connect to other parts) (see if there is a filter on drupal.org that would do this.)