Feedback wanted: VelocityJS.org Documentation

[julianshapiro]

I just updated the documentation panes on http://VelocityJS.org to include real-time CodePen demos.

Beyond that, what else should be improved? Specifically, which panes contain unclear descriptions or simply lack sufficient detail?

I do not plan on hosting the documentation on GitHub at this time (it'll result in too many PR's and I only have so much time), so please respond with your change requests as a comment in this thread, and I will promptly consider each and every request.

Thank you so much in advance. One of my top priorities is great documentation, so this is very helpful to me :)

[kokarn]

I find the text to be really nice but the two-column layout doesn't really suit this kind of content.

Also i've found that the download part is a bit hidden and could use some clarification.

My suggestion would be one page with general information about Velocity and another page/tab with the documentation.

[Oliboy50]

@kokarn +1 for the two-column layout

It's "scrolling party" now that Velocity has a bunch of options.

[julianshapiro]

Thanks, @kokarn and @Oliboy50 :)

Also i've found that the download part is a bit hidden and could use some clarification.

I just bolded the Download Velocity link, but I presume you mean it's still generally unclear to a total web novice how to include it on their page -- is that correct? If so, do you have any suggestions?

I find the text to be really nice but the two-column layout doesn't really suit this kind of content.

It's "scrolling party" now that Velocity has a bunch of options.

This has been brought to my attention before. Clearly, it's a genuine point of concern :) However, to be honest, I'm fairly reluctant to redesign the docs pages. I could do something like pre-collapse all the documentation panes so that there's less content to scroll through. I'll have to think on this more.

[oisinlavery]

I'll have to agree, the two column layout doesn't work and the docs could be better in general. The sections are difficult to scan at speed and it's easy to get lost. Velocity is pretty feature packed and might warrant splitting into separate pages.

My normal flow when looking at the Velocity docs is to bump up the font and cmd+f for whatever I'm trying to find. It works but could be better.

Check out the docs for Headstart, these are really beautiful: http://www.headstart.io/getting-started.html

Here is an extensive list of really nice documentation sites:
https://github.com/PharkMillups/beautiful-docs/

Good article about documentation
http://www.sitepoint.com/products-documentation-good-enough/

Hope that's not too harsh, if it's any consolation, you're already beating the Greensock docs!!!

[nikola]

The current color scheme is way too subtle. Contrast ratio between background and text should be much higher, especially in the right-hand panels. Also, Open Sans at 13px looks very thin in Chrome 35 on Windows 7, i.e. hard to read.

[cleercode]

I would incorporate simple demos inline as part of the docs.

[julianshapiro]

Okay. I just made a bunch of improvements based on your guys' feedback. Perform a hard refresh on http://VelocityJS.org.

My normal flow when looking at the Velocity docs is to bump up the font and cmd+f for whatever I'm trying to find. It works but could be better.

I just added Documentation ^ links on each pane so that you can quickly jump back to the glossary at any point.

The current color scheme is way too subtle.

I just greatly darkened the text in the documentation panes.

I would incorporate simple demos inline as part of the docs.

I recently included Live Demo links in most of the panes. Going to refrain from inlining demos for now since it would entail a lot of overhead and incur even more scrolling. (Solid idea, though. This was something I was considering for a while.)

I also changed the header from fixed to absolute so that it gets out of the way when you're scrolling.

P.S. @oisinlavery: Amazing links. Thank you so much. I'm looking into these.

[tomByrer]

two-column layout doesn't really suit this kind of content

You can narrow your browser to mobile width so the @media rule kicks in for 1 column.
Honestly 2 columns is better, because 1 column would be harder to read (too wide) &/or contain too much white space. Plus the current side-bar background helps keep the sections separate; I don't understand what the problem is.

It could use a bit sprucing up extra space for a about/home page, a bit more icons/images/live examples to make people say "oohh!!" without overwhelming them.

For the API docs, I prefer the layout where there is 1 column explaining, and a parallel column with example code.

Both could use CodePen or other 'live' examples.

[ocombe]

I really don't like the background color, a white background would be better for readability I think.

Also we need more space, more margins. Everything is too condensed. No one reads technical doc on phones, use the space, you probably could add at least 1/3 more width.

It would be nice to have a floating menu on the right or left (or maybe something fixed at the top) like we have on bootstrap, because when we start to scroll down we have to scroll all the way up to find the main links, or use CTRL+F.
And it would be good to have a real menu. The most useful part for the moment is:

Documentation

Basics:  jQuery Arguments Properties Values Chaining
Options:  Easing Queue Complete Begin Progress
Options (cont'd):  mobileHA Loop Delay Display
Commands:  Scroll Stop Reverse fadeIn/Out slideUp/Down
Features:  Transforms Hooks Colors Sequences
Advanced:  Value Functions Forcefeeding Utility Function
Plugins:  UI Pack

Lives demos of all features: codepen.io/julianshapiro

But it's not even at the top of the page, and again it's too condensed.

And add bigger titles to make the different parts of the doc more separated.

[msurguy]

Prepared a small proposal for velocity website redesign. Please see the screenshot attached.

The single column layout with a sidebar would make a great improvement. The logo and a demo of Velocity right in the header would give the potential user an idea about the product right away.

Here's the logo in full size.

[ocombe]

Oh yeah that's really nice !! Good job !

[Oliboy50]

Yup, could be nicer this way. Good Job.
It's a common documentation design, but it's a lot more readable.

[mike-rob]

There is a problem with some of the example code under the Feature: Sequences > Advance section.
Line 4 of the first code example is really long and has it's own scroll bar, making it really hard to read.
It looks like its should be split across multiple lines.

[julianshapiro]

Thank you, man with two names @mike-rob!

There was a bug in Rainbow.js and I couldn't get around it, so I removed the code example altogether.

I've also cleaned up the Sequences section in general; it was worded poorly.

More importantly, I am working on this: #94. That will be the key to making complex sequence generation easy as pie for all users. Stay tuned.

[julianshapiro]

@ocombe: I love how you've channelled your rage into constructive criticism. Thank you! :-D

I really don't like the background color, a white background would be better for readability I think.

I'm going to keep the background color as-is. I think it looks and reads fine. If others have this same complaint, however, please let me know and I'll reconsider.

Also we need more space, more margins. Everything is too condensed. No one reads technical doc on phones, use the space, you probably could add at least 1/3 more width.

I agree, although I'm refraining from going to that extent for now. Good news is that I just increased padding slightly on all the documentation panes. It feels a bit less cramped now.

It would be nice to have a floating menu on the right or left (or maybe something fixed at the top) like we have on bootstrap, because when we start to scroll down we have to scroll all the way up to find the main links, or use CTRL+F.

As mentioned, I recently added "Documentation ^ jump-back-to top links now. I think it works quite well, no?

Documentation is not even at the top of the page, and again it's too condensed.

I just rearranged some content so that Documentation appears higher up on the page (without having to scroll to see it).

And add bigger titles to make the different parts of the doc more separated.

That won't really fit into the current design very well. At this point, if I make further visual changes, it'll be an overhaul to something like what @msurguy has graciously put together.

[ocombe]

Sorry, I was really pissed off yesterday but it has nothing to do with you lib that I really like (just a client who changes his mind every 5 minutes...) :)
The proposition of @msurguy resolves most of my concerns, I find it really nice.

[msurguy]

If @julianshapiro gives me a go, I'll submit a pull with the docs re-done in a much more readable format like I've shown in a screenshot. I think the improved presentation of this product is a guarantee of more people finding it useful, sharing and keeping the momentum going.

[Oliboy50]

@julianshapiro I found something weird in the documentation Scroll pane: here

The offset option looks like part of the Horizontal Scrolling feature.
I guess you could just get rid of the Horizontal Scrolling separator, don't you think so?

[julianshapiro]

@Oliboy50. Oops! Great find. Fixed :)

[julianshapiro]

@msurguy:

Amazing work.

Two reasons why I'm apprehensive to move forward: 1) I actually like the current docs design and layout. 2) The docs' HTML/CSS is currently laid out in a way that a series of small helper scripts rely upon.

I am, however, certainly interested in seeing the final result of what you've begun designing. But, I'm hesitant to ask you to move forward because it's very possible I would not ultimately use it, and I do not want to waste your time. But if you decide to move forward, by all means I will seriously consider the final result when you're done.

[bhongy]

I like the newly added Changelog section in README.md. It is helpful to be able to tell what is new/changed.

Might be helpful to add the link to this section on Velocity homepage.

[julianshapiro]

Yeah, it was pretty stupid of me not to have added it earlier :)

[bhongy]

I think it did not matter much in minor releases but, now, it is really helpful. Good timing. :)

It would help to have the current version (showing changelog might just solve this same thing) on Velocity.js Homepage. Personally, I go to Github and look for the most recent tag to see if the new version is out but for some people, they might not be aware that the update is out.

Also, making Infinite Loop more discoverable might be a good idea. For an easy solution, I think you can just put a link in the Loop section.

[julianshapiro]

@bhongy,

I agree with both your suggestions. I will make these changes late next week when I'm back from traveling :)

[julianshapiro]

This thread got sidetracked from my initial intention of polling for content (not design) improvements in the docs :)

@bhongy: Your recommended changes will go live in the docs shortly. Thanks again.

And thank you again to everyone else. I hugely appreciate all your input, and I recognize that not everyone is a fan of the two-column layout :) I will follow up with @msurguy about further design related changes.

[julianshapiro]

Thought about it quite a bit. I will actually go ahead and redesign the docs next week. I'll reduce the extreme amount of scrolling by switching to a single-column layout, and I'll likely increase font size. Thanks, guys.

[julianshapiro]

Special thanks to @msurguy and @ryanschmidt.

[bhongy]

I was just thinking about it today. Agree with larger font size and having the content in the middle & widen the width of the container. Using tabs for main sections might help with the scrolling issue.

[ryanschmidt]

👍

[Rycochet]

I'd rather like to see a position: fixed quick nav section on one side (media query for larger screens etc) - to save me ctrl+f all the time, and possibly position:sticky on the .dataHeader sections (not supported in very many browsers yet, but it's nice to have) - the width thing is the only bit that's always bugged me - less than 500px wide on a 2600px screen is a bit of a vertical nightmare :-P

[julianshapiro]

OH MY GOSH!!! GREAT NEWS!!! I ACTUALLY IMPLEMENTED ALL YOUR FEEDBACK INTO THE DOCUMENTATION!!

With the exciting CAPITALS out of the way, check it out: http://VelocityJS.org.

Easier to navigate, easier to read.

Thanks to @ryanschmidt and @msurguy.

[bhongy]

Nice! I like the new design.

[ocombe]

Ahhh so much better ! Nice !

[Rycochet]

Looks really good. My only comment is that the section headings (ie "Basics: Arguments") are less obvious than the section subheadings (ie "Overview") - I tried changing it to font-weight:bold (700) rather than 600 and it made it stand out a lot better.

As a general comment on the page - when you add a new feature you put a nice red "This behavior is new. Ensure you're using the latest version of Velocity." - show the version it was added as well? Might be useful for people to check actual version numbers if they don't have control of which version of velocity is available to them (corporate requirements etc) :-)

But anyway - looks really good, and makes things a lot easier to find :-)

[dillinghamio]

Love it, was actually reading the docs & refreshed and the changes were there. I exhaled =)
I agree with @Rycochet , so I added a style to the headers, maybe something you'd want to add.. or not. Great work though

#data > li .dataHeader, #documentation > li .dataHeader {
     padding: 0.5em;; // adjusted padding
     font-size: 2em; // increased font size
     background: #555; // added background color
}

#data > li .dataHeader .dataHeaderTitle, #documentation > li .dataHeader .dataHeaderTitle {
     float: left;
     font-family: "Helvetica Neue", "Helvetica";
     font-weight: 600;
     color: #f5f5f5; // added color
}

#data > li .dataHeader .dataHeaderIcon, #documentation > li .dataHeader .dataHeaderIcon {
     float: right;
     padding-top: 4px;
     color: #FFFFFF; // made white to contrast background
     font-size: 14px; // set font size to not inherit title size
}

a.demo { // positioned the button
    top: -4px;
    left: 10px;
}

.demo:after {
     content: "Demo";
     padding: 0.15em 0.45em 0.15em 0.35em;
     background-color: #4fbc77;
     border-radius: 2px;
     border: 1px solid #dcecf4;
     font-size: 12px; // increased font size
     color: #fff;
     letter-spacing: 0.05em;
     text-transform: uppercase;
     text-shadow: 1px 0px 1px #707070;
}

[dillinghamio]

body { background-attachment: fixed; }

[julianshapiro]

Thanks, @Rycochet and @briandillingham. <3 <3 <3 <3

I just increased the font-size on the docs section headers a bit. Going to refrain from giving them a background-color for now.

As a general comment on the page - when you add a new feature you put a nice red "This behavior is new. Ensure you're using the latest version of Velocity." - show the version it was added as well?

I agree I should do that, but I don't feel like maintaining that. Plus, I like repeatedly forcing people to upgrade to the latest version :-D

@briandillingham Thanks so much for doing the coloring though. You. Are. Awesome.

body { background-attachment: fixed; }

I actually have it the way it is on purpose. Currently there is indeed a strange repeating pattern, but it looks better overall if you ignore that part :-D

[Rycochet]

And just noticed another weird little thing - the page header has a :before hover showing the url to github - which appears out of sight above the top of the page. The header itself also scrolls up and out of view with the page, but the left navigation pane leaves the same space above it rather than scrolling up slightly to make the space less obvious (position:sticky style) :-)

[julianshapiro]

@Rycochet: You are awesome. Not sure what I'd do without you.

I agree with both points, although both would be a pain in the ass to fix so I might leave as-is for now. Will chew on it :) Thanks, as always.

[kokarn]

Great work Julian! Looks way nicer and much easier to use.

Found one small bug tho, if you are say on a laptop with a smaller screen
you cant actually see or scroll to the bottom of the left list.

I'm on a 13" MacBook Pro with a Retina display if that helps.

On Thu, Jul 31, 2014 at 5:41 PM, Julian Shapiro notifications@github.com
wrote:

@Rycochet https://github.com/Rycochet: You are awesome. Not sure what
I'd do without you.

I agree with both points, although both would be a pain in the ass to fix
so I might leave as-is for now. Will chew on it :) Thanks, as always.

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

[Rycochet]

The media query is set to hide the left panel if the screen is too narrow - might be an idea to change it to too short instead as there are some weird display ratios out there - either that or make it scrollable when the thing gets too short (and then disappear when too short and too narrow etc).

[dillinghamio]

Could solve @kokarn's post with adding a scroll bar when the window height exceeds the glossary height, a reduced height to account for the top header, and extra width to account for the scrollbar.

if($('#glossary').height() > $(window).height()) {
    $('#glossary').css({overflowY: 'scroll', height: '90%', width: '120px'})
}

[Rycochet]

@media screen and (max-height: 740px)
#glossary {
   overflow-y: auto;
   bottom: 0;
   height: auto;
   width: 7em;
}

Though can probably fold most of that into the main css - especially if the height is set to auto all the time and the width is corrected for scrollbar when needed etc.

[julianshapiro]

Updated. Thanks, guys.

[Rycochet]

The width of the bar needs to be a little bit more - there's not enough space between the text and the scrollbar (only half an em or so), and the media query for hiding the bar needs to be increased slightly as it lets the main text get behind it - only minor amounts, but it'd look better ;-)

[Rycochet]

Well... I'm not a fan of fb (hence my less than visible presence on it), but having to add support for a client I've been on their dev site, and there's a couple of things I like on it (shock horror!) that I think would be cool for the Velocity docs -

• When clicking a link on the sidebar scrollTo it rather than jumping straight there.
• Highlight the currently visible section (maybe even auto-generate the entire sidebar based on the main docs - save having to manually update things - missing Duration in there etc :-P)
• Have the sidebar against the text rather than against the edge (this always keeps it to the left, but if the text gets wider then the media query hiding would need updating) -

#glossary {
   right: 50%;
   margin-right: 475px;
}

• Leave the #nav in position: fixed; all the time (makes the sidebar look weird with the space above - but scrollTo would need to account for that gap - or position elements differently)
• Change the top margin for body to margin-top: 3.5rem; to make things line up better.

(The fb dev page I was on is - https://developers.facebook.com/docs/opengraph/getting-started - yes, I've had to do other things and was missing my velocity fix :-P)

[julianshapiro]

• Animating scrolling: Done.
• Section highlighting: Seems like too much work. Not sure that I want to bother. Wanna code something simple together for me in jQuery? :)
• Position fixed nav: Done.
• Sidebar against text: Done.
• Adjust sidebar marginTop: Done.

Thank you, as always. Make sure you do a hard refresh.

[Rycochet]

Looks good - but need to use left: and margin-left: if it's to the right, otherwise when the scrollbar gets added it hides some of the text ;-)

I'll have a think about the menu - but there's nice classes to iterate to build the menu, parse the text for section:subsection, and watching the .on("scroll") event, then going over those same classes to find the first one who's absolute position is above 0... Ok, doesn't take much thinking about lol

[Rycochet]

I needed 20 minutes to think through something work related, so put together a little bit of code to play with (works by pasting into the console just to see the differences - note that a couple of sections in the main docs are "out of order", so by grouping them scrolling can jump up and down) -

var section, i, s, sections = {}, $section, $glossary = $("#glossary > .dataBody"), $oldBest;
$("#documentation > li[id]").each(function(){
    var $this = $(this),
        words = $this.find(".dataHeaderTitle").text().split(":");
    if (words.length === 2) {
        sections[words[0]] = sections[words[0]] || [];
        sections[words[0]].push([$this.attr("id"), words[1]]);
    }
});
$glossary.empty();
for (s in sections) {
    if (sections.hasOwnProperty(s)) {
        section = sections[s];
        $section = $("<ul></ul>").appendTo($glossary.append("<b>" + s + "</b>"));
        for (i = 0; i < section.length; i++) {
            $section.append("<li><a href=\"#" + section[i][0] + "\">" + section[i][1] + "</a></li>");
        }
    }
}
$glossary.append("<b class=\"update\" style=\"cursor: pointer;\" onclick=\"javascript:alert('If you\'re experiencing an issue, first ensure you\'re using the latest version of Velocity. You can grab it from GitHub.');\">Bugs</b>");

$(window).on("scroll", function() {
    $("#documentation > li[id]").each(function(){
        var $this = $(this),
            offset = $this.offset();
        if (offset.top >= window.scrollY) {
            if ($oldBest && $oldBest.length) {
                $oldBest.css("color", "");
            }
            $oldBest = $("#glossary a[href=#" + $this.attr("id") + "]").css("color", "red");
            return false;
        }
    });
});

The highlighting could probably fire on "load" too, and would no doubt look better with a class and some styling, and yes, there are a couple of places it could get optimised ;-)

[julianshapiro]

Done. Thank you very much, Robin.