Roku Developer Program

[belltown]

For anyone else who's been irked or inconvenienced by the way the Roku SDK documentation has begun to be split into bite-sized pieces, I've put up a page that has links to the last full-page versions: http://belltown-roku.appspot.com/rokudocs. Currently, this applies to the Channel Packaging And Publishing, Developer Guide, and BrightScript Language Reference documents. If any more documents get chopped up, I'll update my web page.

I'm not sure what their rationale was in splitting up their documents in this way, but it makes it incredibly hard to find anything. For example, I forgot the sequence to enable developer mode, and wasted several minutes of my life trying to find which sub-document to search in the Developer Guide to find it. I wanted to look up all references to "utf" in the BrightScript Language documents, which would have involved searching through 9 separate sub-documents. And when trying to help a new developer the other day find a reference to how to take a screenshot of his channel, I just gave up rather than trying to figure out which sub-document to look in.

I've given up hope that Roku will listen to their developers' feedback. If they'd been listening, there would be real full-sized PDF documents by now that we could download, like there used to be, instead of links on a web site that isn't always accessible. I'm sure that as well-meaning as some of them are, they just don't have the resources, and are too busy working on their next big thing. End of rant.

[Komag]

Maybe it's a horribly shortsighted misguided attempt to save bandwidth? :?:

[EnTerr]

"belltown" wrote:
I'm not sure what their rationale was in splitting up their documents in this way, but it makes it incredibly hard to find anything. [...] I've given up hope that Roku will listen to their developers' feedback. If they'd been listening, there would be real full-sized PDF documents by now that we could download, like there used to be, instead of links on a web site that isn't always accessible. I'm sure that as well-meaning as some of them are, they just don't have the resources, and are too busy working on their next big thing. End of rant.

"Never attribute to malice that which is adequately explained by [simpler means]"
I often have to repeat myself that when dealing with things Roku.

The move from PDF to wiki made sense, considering the lack of discipline in updating the documentation (cue the "release notes" that may or may not be updated months after release). It ensures we have the latest documentation without a formal generation/release cycle for PDFs - decreasing delay from weeks and months to days (technically, minutes even). It also makes it easy for RokuMarkn and RokuKC, when reading about minor issues with the docs, to fix them on-the fly, shall they be in the mood. Also, if i remember, Confluence has a self-service feature somewhere to generate PDFs from selection of pages, i hope that still works.

The recent document chopping to pieces makes no sense, however. There is a fine balance, a right middle-ground of how big information pages should be - and the new size is too fine of a grind indeed. It's not a piece meal of info - instead it's a puree, a chopped liver. I wonder what possessed the technical writer.

But you know what? We should speak up, like you just did. Roku employees are only human and cannot read minds. Yes, i saw documents got chopped to pieces couple of months ago, it bothered me but i said nothing. Anybody else?

Which option do you lean towards, people - "chunky" or "smoothie"?

[belltown]

Good points. I tried the 'Export to PDF' feature. However, it only exports a single page, even if you're on one of the old full-html page documents such as the BrightScript Language Reference. I have no problem with them keeping the up-to-date docs in html; however, I'd really like to be able to export my own PDF copy of the whole document. That would also help cut down on their bandwidth, as I would only be referencing sdkdocs.roku.com when I decided I needed a more up-to-date copy.

[EnTerr]

"belltown" wrote:
I'd really like to be able to export my own PDF copy of the whole document.

Luckily, that is possible from (deep)Space Operations page. Makes a decent looking 8.5MB PDF, see here viewtopic.php?f=34&t=71895

[TheEndless]

Just a guess, but as long time developers, I suspect it's more of an issue of change than it is with organization. The new organization actually seems pretty intuitive, if you don't have the "this used to be on this page!" bias going in. Previously, it was organized more like multiple disjointed documents. Now it's organized more like a single document. With that said, I've definitely stumbled quite a few times over the past few weeks looking for information that I used to know exactly where it was.

[belltown]

With everything for a given document on one html page you, don't have to know what section something's in, just what main document to look in. Even that can be problematic for new developers: they might think to look in the Developer Guide to find out how to create a Developer Account, and after searching through the multitude of "child" pages looking for the relevant information (The Roku Channel Developer Program, Development Environment Overview, Development Overview, Loading And Running Your Application, etc, if they're lucky, they'll realize they need to look in the Channel Packaging And Publishing document, but which "Child Page"?

If Roku has a compelling reason to split up the documents, then the documents' Table of Contents need to reflect the new split and actually show ALL the child documents, not just the top level. Let's say I want to find out how to take a screenshot of my channel, the sdkdocs site gives no clue on its main TOC page. The first layer in the table of contents offers me a choice of documents (although it's not obvious whether to pick the Developer Guide or Channel Packaging And Publishing. Let's say I guess right and pick the latter, and open up the caret to show the document's contents list, all I get is the top-level items: Getting Started, Packaging Your Application, Managing Channels, Common Scenarios, Roku Billing and In-Channel Purchasing. You have to click through each top-level item link to get to the next level, e.g. Packaging Your Application shows another list of child links, at the bottom of which is Generating Screenshots -- This really should be visible in the main Table of Contents.

[TheEndless]

"belltown" wrote:
With everything for a given document on one html page you, don't have to know what section something's in, just what main document to look in. Even that can be problematic for new developers: they might think to look in the Developer Guide to find out how to create a Developer Account, and after searching through the multitude of "child" pages looking for the relevant information (The Roku Channel Developer Program, Development Environment Overview, Development Overview, Loading And Running Your Application, etc, if they're lucky, they'll realize they need to look in the Channel Packaging And Publishing document, but which "Child Page"?

If Roku has a compelling reason to split up the documents, then the documents' Table of Contents need to reflect the new split and actually show ALL the child documents, not just the top level. Let's say I want to find out how to take a screenshot of my channel, the sdkdocs site gives no clue on its main TOC page. The first layer in the table of contents offers me a choice of documents (although it's not obvious whether to pick the Developer Guide or Channel Packaging And Publishing. Let's say I guess right and pick the latter, and open up the caret to show the document's contents list, all I get is the top-level items: Getting Started, Packaging Your Application, Managing Channels, Common Scenarios, Roku Billing and In-Channel Purchasing. You have to click through each top-level item link to get to the next level, e.g. Packaging Your Application shows another list of child links, at the bottom of which is Generating Screenshots -- This really should be visible in the main Table of Contents.

Do you not see the treeview on the left when you're browsing the site (I know on my tablet, it doesn't always show up)? That allows you to expand it to see all of the sub-pages without having to follow any links, just like you would in a PDF, incidentally. Of course, it automatically collapses as soon as you choose a page, which can be extremely frustrating.

[spoiler=Expandable ToC:3kcd15aq][/spoiler:3kcd15aq]

[belltown]

The trees don't go down all the way. For example, on the image your posted, the Developer Guide document shows a Development Environment Overview child. However, there are 7 children and 7 grand-children below that which are not shown on the table of contents side-panel. The Channel Packaging And Publishing document only shows the top 5 children, but none of their children, e.g. the child of the Packaging Your Application link that has a Generating Screenshots child. If they can show the Developer Guide grand-children under Developer Guide>Video Streaming, they I don't see why they're not showing the remaining Developer Guide grand-children.

[TheEndless]

"belltown" wrote:
The trees don't go down all the way. For example, on the image your posted, the Developer Guide document shows a Development Environment Overview child. However, there are 7 children and 7 grand-children below that which are not shown on the table of contents side-panel. The Channel Packaging And Publishing document only shows the top 5 children, but none of their children, e.g. the child of the Packaging Your Application link that has a Generating Screenshots child. If they can show the Developer Guide grand-children under Developer Guide>Video Streaming, they I don't see why they're not showing the remaining Developer Guide grand-children.

The tree only shows individual pages. The 7 children/7 grand-children you're referring to are actually just hyperlinks to sections on that same page. The same is true for the Channel Packaging and Publishing "children" which is just the breakdown of topics on that specific page. In contrast, the children under Developer Guide->Video Streaming are separate documents/pages, which is why they are in the tree.