#727 ✓ resolved
David Seifried

Analyze current documentation and create plan of attack

Reported by David Seifried | September 20th, 2011 @ 01:49 PM | in 1.0 Release (closed)

Our documentation has not been touched in some time and one of Humphs students is excited to work on fixing that. She is going to go over our existing docs, tell us what she thinks, and togethor we are going to formulate a plan of attack to complete them all on our push to 1.0.

This ticket will serve as a place to throw our thoughts on the docs, a good overall style for them, and what needs to be included in documentation.

Comments and changes to this ticket

  • Saba Naqvi

    Saba Naqvi September 20th, 2011 @ 02:00 PM

    • State changed from “new” to “assigned”
    • Assigned user set to “Saba Naqvi”
  • Rick

    Rick September 20th, 2011 @ 02:02 PM

    • State changed from “assigned” to “new”
    • Assigned user cleared.

    Please touch base with Richard Worth (rworth on irc), he's in the process of redesigning and developing our docs

  • Rick

    Rick September 20th, 2011 @ 02:09 PM

    Adding Richard D. Worth to notifications

  • David Seifried

    David Seifried September 20th, 2011 @ 02:12 PM

    Saba is going to be more working more on actually filling out our documentation more thoroughly and going over what is missing from the current docs. From my understanding what Richard Worth is doing is more back end work. Saba is one of Humph's students this semester and is going to be starting off with going over our current documentation and providing us with updates on the current state of our docs and creating discussion on how we can make them better. All of this work will be going towards her 0.1 release in Humph's class so I think this should be left open and as is.

    If both Saba and Richard are going to be working on the docs, this is a great place for all of us to leave input on the current state of them and I'm sure that they can tackle this together.

  • Rick

    Rick September 20th, 2011 @ 02:51 PM

    Awesome!

    I know that Richard plans on developing all of the docs stuff via git/github, so Saba will be able to collab with him very easily there.

  • Saba Naqvi

    Saba Naqvi September 22nd, 2011 @ 12:11 PM

    Hi guys, thank you so much for making it easier for me to blend in the team by introducing me around. Is it possible to meet Richard Worth in person? I feel it would be easier to introduce myself and discuss about the documentation in person. Then later on I can ask questions on either IRC or lighthouse. =)

  • Saba Naqvi

    Saba Naqvi September 22nd, 2011 @ 12:17 PM

    • Assigned user set to “Saba Naqvi”
  • Rick

    Rick September 22nd, 2011 @ 12:23 PM

    Saba, Richard actually lives in Virginia. Next time you're on IRC i will introduce

  • Saba Naqvi

    Saba Naqvi September 22nd, 2011 @ 12:32 PM

    ohh gosh ok... I dont think I am going that far but ya I will come on IRC. Please give me a kind of timeline or something like the best time that he comes online, so that we have enough time before he goes offline.. thank you =)

  • Rick

    Rick September 22nd, 2011 @ 12:37 PM

    We're both on IRC from about 8am to 12midnight EST (both on now :D )

  • Saba Naqvi

    Saba Naqvi September 22nd, 2011 @ 12:47 PM

    okay cool.. I will be there today evening

  • Saba Naqvi

    Saba Naqvi September 26th, 2011 @ 03:00 AM

    I have attached my overview of documentation please have a look at it. Its in notepad format.

    Thank you,
    Saba

  • Scott Downe

    Scott Downe September 29th, 2011 @ 02:35 PM

    By going over that document, I see this as more of a documentation layout, than documentation content, which is fine.

    Maybe the next step would be to sort out the contents of that document into new tickets.

    From there, the tickets can be reviewed, fixed, or set to invalid on a case by case basis.

    Keeping things in that document is good for now, but if that doesn't become tickets soon it will get lost.

  • Saba Naqvi

    Saba Naqvi September 29th, 2011 @ 03:23 PM

    thanks for the pointer Scott. It seems a very good suggestion. I will definitely start doing that for my next one. By following your suggestion I will try to open next ticket which would be my main page. I have done some documentation in it. At least, the introduction part. I will update the Main page as I gather up more and more info and also with help of suggestions and teams input. Below are my pointers that I wanted to mention as to what I had in mind when I was putting up the doc skeleton. I have tried to sketch a very clear picture of what the documentation would look like once its done.

    There are 4 basic pages that I talk about in my documentation
    1) Main Page
    2) Guide Page
    3) API Page
    4) FAQ page

    I am going to talk about them one by one.

    1) Main Page
    ========== Main page would contain an introduction for general public and for developers. Next it will contain the headings and links to the pages for Guide, API and FAQ. I had thought of this format for the reason that Guide, API and FAQs will expand in the future and it will be easier to do that if they are in their separate individual pages. This format will make the main page less crowded, fairly simple and easy to navigate.

    2) Guide Page
    =========== This page would contain all the links to the guides that we presently have and every link would lead to their own individual page. We presently have this format but the only difference is that instead of having them all in the main page, it would be better to have them all in a separate Guide Main page. Also I would like to point out that for each guide we currently have an audio clip along with a snippet of code show casing how to use the code which is really impressive. One thing that struck me was that, what if the user does not support audio or is not able to use the speaker for some unknown reason? What I had in mind was that we can keep what we have right now and add intro for that particular guide and also have a box which would contain the written script of the audio clip.

    3) API Page
    ========== API page would have its own list of APIs on its page and like Guide page each API would have its own individual page with its own intro and description.

    -In this page there would be four headings mainly:-

      -Instance Method
      -Instance property
      -Plugins
      -Static Method
    

    -Under each method/property/plugin we can have the set of methods that we currently have. For example, Instance method would have links to the instance methods we currently have [.enable(plugin)] and each link under the Instance method would lead to and individual instance method link, i.e, .enable(plugin) would have its own individual page with description of the way its used, when its used and how. We currently have a method and a very show info for it which needs to change.

    -each individual page would have a site map that would help the user to go back to the main API page or the main page itself.

    4) FAQ Page
    ========== This page would have different questions and answers that the user might have. We can also include questions or concerns from our community column here. This would make the users feel that they are heard.

    Any input, pointers or suggestions are highly welcomed =D.

    Thank you.

  • Saba Naqvi

    Saba Naqvi September 29th, 2011 @ 03:36 PM

    Hi, I have followed Scott's suggestion and opened a new ticket for the main page documentation and here's the link
    https://webmademovies.lighthouseapp.com/projects/63272/tickets/748-...

    Thank you

  • David Seifried

    David Seifried October 7th, 2011 @ 04:18 PM

    I just sat down and looked over our plugins and I like a lot of what Saba has mentioned. I think doing something like what jQuery does would be a cool idea http://docs.jquery.com/Main_Pager , which is also like what saba mentioned. A main page to navigate through each of the parts of the api and links to individual pages for each method and such. Our current docs look more like shorthand explanations, like this page at jQuery http://api.jquery.com/category/attributes/ , and if we used what we have as such I think that would be cool. We then have an individual page for each method going in detail like here http://api.jquery.com/addClass/ . I like how there is a basic 1 line explanation, then it goes into greater detail with code examples, how it can be used, and so on.

    I think seeing our Docs go in a similar direction would be awesome. Coming from someone who has only used jQuery here and there and using there docs from time to time I can say that they do the trick and give me what im looking for 99% of the time.

    What ive also noticed is that were missing a good bit of stuff in our docs as well ( which makes sense since we did quite a few changes to our API last release ). Over the next week im going to go over everything now that the API is frozen and begin writing some basic explanations for everything we are missing, and adding content where it is missing from the current docs. We also need to document how players and plugins are used from a users standpoint, as this isnt documented anywhere. Using a player like youtube vs just the baseplayer vs an HTML5 video are done slightly differently, so we are going to have to document it well, showing use cases for each and such. Bretts early made guides are sadly now not accurate due to the player re-write from last release.

    On our call this afternoon it was expressed that these guides are tedious to make and probably wont happen anymore, which is fine, but I think having something similar in each of our docs would be awesome. A small html code example in each of the docs and a small demo underneath that would be super helpful to everyone to see exactly what functionality is being showcased. I think a lot of common questions can be solved by showing examples in our docs and being a video HTML5 video framework we may as well have a video demo of the example on each page.

    We also need to document how to get someone involved in the project, from forking and cloning our repo, to reading the style guide and so on. It would probably benefit everyone to have a small set of instructions to do when they want to work on the project. We can then write a small set of docs for creating a plugin, player and so on. We could also benefit from a small doc on how to file a bug with us. Going to lighthouse, what type of explanation to give, and a reduced test case of where the bug is.

    Im going to attempt to get in contact with richard worth to see where he is at on this and get some thoughts on all of this

  • David Seifried

    David Seifried October 11th, 2011 @ 05:04 PM

    Here are some brief outlines ( like the current docs ) of what is missing. Im gonna throw these up now and get some feedback on them and make sure I didn't miss anything. Lemmie know your thoughts on everything and once it seems as tho Ive nailed everything im gonna start writing in depth explanations for everything as well as some examples. So here goes:

    Instance Methods:

    load()
    - Forces a reload of the current instances video element

    controls( true|false )
    - Specifies whether to show or hide the controls for this instance

    preload( state )
    - provide a hint to the user agent as to how much/what type of data should be preloaded

    autoplay( true|false )
    - Specifies whether the video should automatically start playing or not

    loop( true|false )
    - forces the video to restart and begin playing again once it reaches the end, defaults to false

    muted( true|false )
    - start the video muted or not, defaults to false

    buffered()
    - returns a TimeRanges ( link to explanation of the object here ) object that represents that amount of data that has buffered

    readyState()
    - returns a values ( between 0 -4 ) describing to what degree of the video is ready to be rendered at the current playback position

    seeking()
    - returns true or false, describing if the video is currently seeking or not

    paused()
    - returns true or false, describing if the video is currently paused or not

    played()
    - returns a TimeRanges object that represents the amount of the video that has played so far

    seekable()
    - returns a TimeRanges object that represents the amount of the video that the user can seek through

    ended()
    - returns a true or false, describing if the video has reached the end of its duration yet or not

    roundTime()
    - returns a rounded currentTime ( to the nearest second )

    unmute()
    - convenience method to unmute the medias sound

    toggle( plugin )
    - toggles the state of a plugin to be either enabled or disabled

    Instance Properties:

    data
    - an object containing data pertaining to the instance ( trackEvents, history, ect )

    isDestroyed
    - boolean value describing if the instance is destroyed ( had all of its event listeners removed ) or not

    Popcorn property:

    registry
    - an array of objects storing data on each plugin that is included

    registryByName[ name ]
    - returns an object that is keyed by the passed in name

    I still have a few more to do, but this is a start for now.

    Any feed back anyone has is awesome!

  • David Seifried

    David Seifried October 12th, 2011 @ 03:25 PM

    Heres some more:

    Static Methods:

    error( msg )
    - specifies an error message to be thrown by popcorn

    sizeOf( obj )
    - returns the number of items in a specified object

    isArray( array )
    - returns true or false, stating whether the passed in item is an array or not

    nop
    - short for No Operation Performed, simply an empty function

    destroy( instance ) /* also an instance method, which takes no argument * /
    - removes all event listeners from the passed in instance, rendering it inoperable

    addTrackEvent( obj, track )
    - inserts a trackevent on a specified track that is cued to be displayed

    removeTrackEvent( instance, trackID )
    - removes the specified trackEvent, resulting in it no longer being fired

    getTrackEvents( instance )
    - returns an array of all trackEvents on an instance

    getTrackEvent( instance, trackId )
    - returns a single trackEvent from the given track on a specified instance

    getLastTrackEventId( instance )
    -returns the id of the last track event on a given instance

    timeUpdate( instance, event )
    - update the position of the trackEvent pointer, showing/hiding trackEvents as necessary

    removePlugin( instance, name )
    - removes all trackEvents of type 'name' from the specified instance. If instance is empty, removes from all instances

    compose( name, definitionObject, manifest )
    - create an effect of the given name, which adds additional functionality to a plugin based on the definitionObject

    I think I pretty much hit everything here. Let me know if I missed something or if anything can be worded better and so on. The more feedback we get on these docs the better.

    Im going to begin writing in depth docs for these now, and as I finish one Im going to create a ticket for each one and put it up for review to get some feedback on it.

  • Rick

    Rick October 12th, 2011 @ 07:55 PM

    I appreciate your research, but there are a number of things that should not be publicly documented - regardless of whether or not they are exposed. No end developer should ever be accessing .data, .isDestroyed, Popcorn.registry, Popcorn.registryByName. As for static methods, no reason to document: error(), sizeOf(), isArray(), nop(), destroy() (use the instance call instead), or any of the static track event methods - Butter and Popcorn Maker are the only reason that the most of the static track and plugin methods exist. I dont think we should be offering timeUpdate() either.

    compose() should be documented

  • David Seifried

    David Seifried October 13th, 2011 @ 05:49 PM

    Awesome thanks for the input Rick. Gonna just document the necessary as you mentioned.

    Documented a few to start with if anyone wants to take a look at what ive done so far, there here:

    http://github.com/dseif/popcorn-js/tree/docs

  • Saba Naqvi

    Saba Naqvi October 14th, 2011 @ 01:53 AM

    Hi,
    Dave and I have joined forces so to speak and I would be working with him over documentation. Dave had given me 5 methods to document and had advised a plan for documentation. Below is the documentation as per how Dave mentioned how the methods need to be documented. I have tried my best to give good explanation for the methods but since I am just started to understand the code and might have missed some points and therefore, I would love to have sort of points or advice or comments.

    ....................................................................................................................

    play()

    Description
    When .play() method is called a "play" event is triggered. This method is usually used to play a video. This function is merely used and not extended as its a native function. This method is flexible enough that it can be used anywhere in the code and be called or triggered as much as the user requirers it.

    Code Examples

    Link - popcorn-js / players / baseplayer / popcorn.baseplayer.js
    //Play method here is used to check if the condition applies // if play was called before player ready, start playing video

        !basePlayer.paused && basePlayer.play();
      });
    

    - Link - popcorn-js / players / baseplayer / popcorn.baseplayer.unit.js
    //Here the play function is being called inside a locally declared variable, therefore when this variable is triggered, the play function is called. player.play();

    - Parameters
    For most of the time it can run without parameters but when used with parameter for example, play(time) can eliminate the need for setting the current time when playing media files.
    ...................................................................................................................................................

    pause()

    Description
    This function pauses the video and triggers the "pause" event and also returns the Popcorn instance object. This function is merely used and not
    extended as its a native function. This function can also be called or triggered when we need to pause the video in order to trigger or run a set of events. We can also pass time in the method in order to pause the video for that much amount of time.

    Code Examples:

    //Simple example //here we are declaring a variable and assigning the pause function to the variable. var $p = Popcorn("#video-element-id");

    $p.pause();

    Parameters
    For most of the time it can run without parameters but when used with parameter for example, pause(time) can eliminate the need for setting the current time when playing media files.
    ......................................................................................................................

    currentTime([seconds/arg])

    Description
    This function is usually used to get and set the current time of the Popcorn video object instance. This function is merely used and not extended as its a native function. The method can also be used to fire popcorn's timeupdate. The method can be manipulated to the user's preferred time by passing in the seconds in the method.

    Code Examples

    //Below we get the Popcorn video object instance currentTime and return the currentTime

    var $p = Popcorn("#video-element-id");
    $p.currentTime();

    //Here we are setting the Popcorn video object instance currentTime and returning the popcorn video object. (seconds) moves to currentTime in given seconds. var $p = Popcorn("#video-element-id");
    $p.currentTime( seconds );

    - //Simple code var $pop = Popcorn("#video");

    // Omitting the argument will get the currentTime console.log( $pop.currentTime() );

    // Set to the 5 second mark $pop.currentTime(5)

    console.log( $pop.currentTime() );

    - Link - https://github.com/webmademovies/popcorn-js/blob/master/players/vim...
    //We can trigger a chain of events while video plays. // So the currentTime is set to the previous currentTime. this.previousCurrentTime = this.currentTime;
    //A set of events are then triggerred that.addEventListener( "timeupdate", function() {

          that.currentTime = that.swfObj.api_getCurrentTime();
        }
    

    - link - https://github.com/webmademovies/popcorn-js/blob/master/players/vim...
    // Here the current time is used to Seek the video

    setCurrentTime: function ( time ) {
      if ( !time && time !== 0 ) {
        return;
      }
    

    Parameters
    Number of seconds is usually passed into the method in order to set the currentTime for the popcoen video object.

    ......................................................................................................................

    duration()

    Description
    This methods gets the length of the video. If a variable needs to be called at a certain duration of the video then we can call this method. This method can also be used for checking errors occurring during a certain period of time while playing the video.

    Code Examples
    //Simple code var $pop = Popcorn("#video");

    console.log( $pop.duration() );

    Parameters
    This method can run without the parameters.

    ......................................................................................................................

    exec(time, callback)

    Description
    This is an instance method that executes an arbitrary command at a given time in the video. This method basically executes a function at a given time in milliseconds and therefore, two parameters are needs in order to run this method. We can use the .cue() method is as an alias to the .exec(). This alias can then later be used anywhere in the program however the user requires.

    Code Examples
    //Simple code example // "1" here is the time in milliseconds and Function() here is the anonymous function being called just like callback. var $pop = Popcorn("#video");

    $pop.exec( 1, function() {

    console.log("Executed at the 1 second mark!");
    

    });

    $pop.play();

    //result at the console would be Executed at the 1 second mark!

    - link - https://github.com/webmademovies/popcorn-js/blob/master/popcorn.js
    //here we are using exec in a different way. exec() is being used to check if entity is a valid string id or not

      matches = rIdExp.exec( entity );
    

    - Link - https://github.com/webmademovies/popcorn-js/blob/master/popcorn.js
    //here we using an alias for exec function

    Popcorn.p.cue = Popcorn.p.exec;

    -

    Parameters
    The parameters usually used are time and callback. This method executes an arbitrary callback function at a specific time in seconds.

    time – time location in seconds to execute callback function
    callback – callback function to execute at provided time[miliseconds]

    ................................................................................................................

    The above is a crude form of the actual documentation. We will later have jsfiddle to show working example. At present I and Dave are preparing matter for the documentation.

  • Rick

    Rick October 14th, 2011 @ 02:48 PM

    Be careful... this:

    
      matches = rIdExp.exec( entity );
    

    is not the Popcorn instance method called "exec", it is actually regex exec: https://developer.mozilla.org/en/JavaScript/Reference/Global_Object...

  • Rick

    Rick October 14th, 2011 @ 02:51 PM

    Is the intention to extend the current docs for all those methods? All of the above are currently documented on the site - we really need help documenting the plugins, as none of them have any sort of documentation at all.

  • David Seifried

    David Seifried October 14th, 2011 @ 03:21 PM

    Its both. We want to expand a bit on the current docs as well as document the plugins/players/parsers. Saba took a stab at the basic methods in Popcorn and was going to try to add some content to them. As far as the examples that she posted goes we discussed those yesterday in person and she was supposed to rewrite those and not take examples from files in the popcorn repo but instead write a small html block that can be used in conjunction with the jsFiddles that currently exist. Jon and I spoke yesterday and with think having both a small html text block as well as a fiddle is benefitial in cases where the user may be offline, or a fiddle fails, a videos location changes, ect. Saba said she is going to have a bunch of time this coming week to work on the docs so I told her to work on the plugins as like you said they need some docs.

    Also ive got a few markdown docs finished for some of the methods that were missing if you want to take a look Rick

    http://github.com/dseif/popcorn-js/tree/docs

  • cadecairos

    cadecairos October 14th, 2011 @ 03:35 PM

    For whoever does the plugin docs, I'd them done like this in markdown.

    Don't worry about separate repos like I have here, I can move the docs into my new repos later.

    EDIT: here's the raw text for that mardown, just in case.. https://raw.github.com/cadecairos/popcorn-footnote/master/readme.md

  • David Seifried

    David Seifried October 14th, 2011 @ 03:37 PM

    +1 to Chris' styling for the markdown, might also be a good idea to add a jsFiddle in there as well

  • Rick

    Rick October 14th, 2011 @ 04:48 PM

    @dseif I guess we should start folding in the docs you're working on so that tickets can be filed for them, updates made, etc. I'm going to have a number of structural/informational things that need to be added/updated.

  • Rick

    Rick October 14th, 2011 @ 04:58 PM

    • In the markdown files, inline references to code should always be backticked to indicate that they are code.
    • All references to "HTML video element" => "HTMLMediaElement"
    • "is a native HTML video element method that we have thrown onto each popcorn instance for convenience..." This needs to be reworded to reflect correct information. ie. "is a Popcorn instance method, defined as a passthrough accessor to the HTMLMediaElement prototype property of the same name." --- Most of the methods that are passthroughs, are actually passthroughs to native properties, not methods
  • Rick

    Rick October 14th, 2011 @ 05:01 PM

    I noticed that you've opted to use anonymous fiddles in the docs (http://jsfiddle.net/rQfkB/) instead of the ones that I can go back and edit in my account. We should create an account for Popcorn on jsfiddle - it will allow us to save all of the fiddles that are created and fork from boilerplate fiddles.

  • Rick

    Rick October 14th, 2011 @ 05:05 PM

    The following are methods of Popcorn instances, but properties of HTMLMediaElement: autoplay, buffered, controls, loop, muted (this is going to get confused with mute() and unmute() ), preload & readyState. Currently they are all incorrectly listed as native methods.

    load() is correct.

  • David Seifried

    David Seifried October 14th, 2011 @ 05:12 PM

    Thanks for the feedback Rick, I appreciate it. I agree on creating a Popcornjs jsFiddle account like you stated. Also, for each of these docs, should I be creating them in there own seperate ticket and putting them up for review?

    Seems like a good idea to me as this ticket is beginning to get a but cluttered with all of the people working on it and such.

  • Rick

    Rick October 14th, 2011 @ 05:58 PM

    That's a good question... I'm not sure. My first thought is no, but again, I don't really know :)

    Chris, the code example shouldn't be single line, makes it really hard to follow. The syntax for multi-line code blocks is "```". Also, you've only listed "start" and "end" with only "number". Need to add:

    • "in" and "out" aliases
    • SMPTE (start/in, end/out also support SMPTE strings)
  • David Seifried

    David Seifried October 19th, 2011 @ 11:10 AM

    • State changed from “new” to “assigned”
  • David Seifried

    David Seifried October 19th, 2011 @ 03:43 PM

    • State changed from “assigned” to “new”

    Got all of the core docs up I think with the changes Rick mentioned above. As usual, any feedback is awesome :)

    http://github.com/dseif/popcorn-js/tree/docs

  • David Seifried

    David Seifried October 19th, 2011 @ 04:20 PM

    • State changed from “new” to “assigned”
  • David Seifried

    David Seifried October 24th, 2011 @ 02:30 PM

    • Assigned user changed from “Saba Naqvi” to “David Seifried”

    https://github.com/dseif/popcorn-js/tree/docs/docs/plugins

    any feedback on this would be awesome, lemmie know what you like/dont like and we can go from there.

  • David Seifried

    David Seifried November 2nd, 2011 @ 03:23 PM

    • Assigned user cleared.
    • State changed from “assigned” to “review-looks-good”

    Setting to resolved.

  • David Seifried

    David Seifried November 2nd, 2011 @ 03:24 PM

    • State changed from “review-looks-good” to “resolved”

Please Sign in or create a free account to add a new ticket.

With your very own profile, you can contribute to projects, track your activity, watch tickets, receive and update tickets through your email and much more.

New-ticket Create new ticket

Create your profile

Help contribute to this project by taking a few moments to create your personal profile. Create your profile »

Popcorn.js is an HTML5 video framework that lets you bring elements of the web into your videos.

Popcorn.js is a project of Web Made Movies, Mozilla's Open Video Lab.

Shared Ticket Bins

Attachments

Referenced by

Pages