We have docs/guides in two places

[gkatsev]

We need to

• decide on the place where they should go
• put them there
• remove the other one

[gkatsev]

I'm leaning towards keeping them as markdown in the videojs repo and then having a grunt task in this project that generates those into html for the website.
This way those guides can live with the version they're associated with.

Kind of like the jsdocs are built against a specific version of videojs.

[gkatsev]

@sprice in the main videojs repo: https://github.com/videojs/video.js/tree/master/docs
Should've been a bit more specific :)

[sprice]

Shoot. I deleted my comment (which I posted at the exact same time as your second comment). Thanks for clarifying.

[gkatsev]

Heh, no worries.

[rcrooks]

Are we talking about just the guides? I brought them over just to keep things together, but if you want to generate them from MD in the videojs repo, that's great.

[sprice]

There are three sections to the docs. Guides, Samples, and API Reference. It looks like the Guides and Samples are duplicated between repos, with the docs repo holding what is on the docs website. The API Reference content is built in the docs repo using a video.js checkout and jsdoc.

The problem described in this comment deals with versioning the docs which I've started some work on in #12. One of the solutions I had thought of is to keep the versions of video.js and docs in sync.

The options seem to be:

1. Delete the Guides and Samples from the docs repo. Update the Guides and Samples docs in the video.js repo. Update the docs Grunt task to build the Guides and Samples from the video.js repo it's already checking out.
2. Delete the Guides and Samples from the video.js repo and keep them maintained in the docs repo as they are now.

Going forward with new versions, I think both of these options will keep nicely versioned Guides/Samples. It might get a little messy if we try to version past Guides/Samples.

[gkatsev]

nicely summarized @sprice.

This was brought up because we needed to document a new option for videojs/video.js#2847 and we didn't really know the correct place to put it. The API docs don't really have a good place for them so we looked at the guides and got a bit confused as to which we should use.

I think building the guides from the markdown files in the videojs repo along with generating the API docs from the videojs repo might be the best course of action here.

[rcrooks]

@gkatsev this is still unresolved. I'm fine with either of the options, but if we go with #2, someone's got to do the work of modifying the grunt file to handle the generation of the guides from the markdown. @mboles and I built the grunt file, and could do this, but it will take some time, as we're pretty busy with other stuff and also not grunt experts, so will need to do some research on the best way to do this.

[gkatsev]

@rcrooks hopefully I'll have the time for this starting soon.

[rcrooks]

@gkatsev ok, I"m having a look too, and will work in a 'convert-guides' branch. Will let you know if I get it working

[rcrooks]

@gkatsev you can let this one go - I'm 99% there - will be done tomorrow

[mister-ben]

How is this shaping up?

[rcrooks]

Guides are now copied in the api doc- generation process. No more editing
content in the docs repo

On Thu, Jan 7, 2016 at 12:57 mister-ben [email protected] wrote:

How is this shaping up?

—
Reply to this email directly or view it on GitHub
#14 (comment).

Robert Crooks
Director of Learning Services
Brightcove, Inc

[gkatsev]

@rcrooks oh, sweet. I guess we can close this issue then?

[rcrooks]

Yes

On Thu, Jan 7, 2016 at 20:13 Gary Katsevman [email protected]
wrote:

@rcrooks https://github.com/rcrooks oh, sweet. I guess we can close
this issue then?

—
Reply to this email directly or view it on GitHub
#14 (comment).

Robert Crooks
Director of Learning Services
Brightcove, Inc