Documentation difficult in v2

[baweaver]

https://jasmine.github.io/1.3/introduction

In version 1.x the documentation was very straightforward for getting started. I'd had another developer ask me how to write Jasmine, and I'd asked what they meant as the getting started guide was very clear last time I read it. I tried finding that information on the new site just to see what they meant.

I was expecting the getting started link to provide something like the introduction in 1.3, but ended up with a lot of "how to get started in x". This is useful, but I couldn't find a general "how to write jasmine" section from there.

Perhaps I was looking in the wrong place, but I feel that the site should be organized to expose this information more immediately.

[sgravrock]

The equivalent page for 2.8 is https://jasmine.github.io/2.8/introduction, which is reachable via the docs link in the header. I'm open to suggestions (and pull requests!) for how to make that part of the documentation more discoverable.

[slackersoft]

The documentation for Jasmine has been pretty heavily revamped recently. We now have more obvious getting started guides for node.js, ruby, and python, as well as a new tutorial about writing your first suite. All of these are linked from the main docs page.

Hope this helps. Thanks for using Jasmine!

[terenc3]

I've also search long to find the newset introduction page. Now i unterstand that after 2.9, the tutorial pages are used.

Sadly i find them very unusable.

1. The font is not monospace
   In the old version the font was set by the docco.css but now the site.css includes a css reset (Check the pre tags).

2. The site is to narrow on big screens. Please add atleast a second media query e.g.
   @media (min-width: 1200px) { .menu, .main-content, .footer-wrapper { width: 1150px; } }
   

@sgravrock IMHO the docs page can be replaced with a direct jump to the tutorials.

API Docs was never visited by me, but maybe it can be placed in the top menu (Releases and GitHub can be moved to Getting Started - Jasmine Standalone block or directly Startpage)
Getting Started has the same links which are already at the Startpage
Archive can be include on the tutorials page and be accesed via a dropdown or an inline list at top and bottom

I hope my comment is not to rash :)

[slackersoft]

I definitely didn't notice the clobbering of the code styles with some of the new changes. I would be happy to review a pull request to fix that to match the other code examples in the API docs.

I also agree that I would like the side-by-side pages (and possibly others) to make better use of horizontal space when it is available, but this mechanism was easier to set up initially to get something that looked decent in the new format. I would similarly be happy to review a pull request that allowed some expansion, but still kept some of the minimum sizing happening currently.

The API docs were one of the most requested features for Jasmine's documentation, but a better site organization and navigation is definitely something I've been thinking about.

[elliot-nelson]

I am working on a custom branch of the jasmine docs and would like to make some potentially larger changes. I thought I'd bounce some off this thread and get your initial reaction...

1. Eliminate the iconic side by side look in favor of the slightly more modern "alternating" text and code block styles favored by similar documentation. Easier to format, easier to read on mobile, etc.

2. Re-introduce the old school "Introduction" page, but pare it down so it introduces each concept and then links into a section to go into more detail. The detail sections would be like "Specs and Suites", "Expectations", "Spies", etc.

3. Auto-generate new Singleton pages for each matcher and spy strategy to go under the appropriate sections. I'd like all this to actually live in the jasmine repo and get generated using jsdoc. I'm currently torn between having e.g. "/docs/matchers/toBeEqual.md" in jasmine core, or just expanding the jsdoc comments inline using new custom tags.

4. Re-skin Jekyll template - keep the classic logo and purple and most of the intro, but sand some rough edges to better compete with competitors like sinonjs, mocha, jest, etc.

(For me and maybe a lot of us, jasmine feels like it's been with us forever -- but new people start coding every day and I think some of the changes above will help jasmine hold onto its market share.)

Another thing I'm not sure how you might feel about is moving ALL jasmine "documentation" into jasmine core. Basically the entire site in markdown format lives in jasmine core under "/docs", and this repo still exists but only has the Jekyll template and generator code. Then instead of versioning just the API, you'd version the entire site. I feel this encourages keeping the docs up to date with code changes and lets you freely edit introductory material without going to a separate project.

[slackersoft]

1. Eliminate the iconic side by side look

I would also like to move the tutorials away from the side-by-side design. It doesn't work as well in the new layout. I managed to rewrite some of the content in the newer format, but some of them were just too big at the time.

2. Re-introduce the old school "Introduction" page

This still mostly exists. The majority of the basics and intro contents are now in the Your first suite tutorial. I haven't figured out the best ways to navigate through the docs, since it largely depends on exactly where you are in the process of setting up Jasmine. You might want to know about install, configure (node.js, ruby, or python), an intro, or just a reference.

3. Auto-generate new Singleton pages for each matcher and spy strategy

This seems like it would lead to a large number of very small files. If the issue is the ability to more easily link to a particular one on the page, I would favor a solution that shows the correct link next to the section in the API docs. This may even be as simple as some css and js to the existing pages since I think the jsdoc templates already render a <span> there. I would also rather not add too much custom code to the layouts of the docs themselves, since that can make it harder to maintain and harder for newer folks to contribute.

4. Re-skin Jekyll template

This is pretty vague, I would have to see what kinds of changes you're really talking about. I agree that some of the general layout here could use some help, but I want to keep the expected use-cases in mind for the docs and not veer too far back to a single page that you have to search yourself.

[elliot-nelson]

Thanks for the feedback, as always! I'll think I'll start slow with some targeted PRs, and we'll see where we end up. 👍

[agirorn]

Not to bash on anyone. And I know it is tough to maintain a project like this and compete with FB.com and all the other big boys. But I feel the doc's are lacking focus. I don't get the feeling they were built to make anyone more efficient in working with jasmine or a better tester.

I think a site like https://jasmine.github.io/ should have these goals.

1. Help users get started working with jasmine.
2. Help users find the current docs for matchers and configuration.
3. Direct you in the right direction if you have trouble working with jasmine (Not solve all the worlds trouble)
4. Other docs that must be there but are of lesser importance.

(Optional) As an extra bonus allow users to do items 1 and 2 for the actively maintained versions and not all versions. Ther should be an end to the maintenance madness.

And this is how the current compare to these goals IMOP.

1. Help users get you started working on jasmine.
It's ok but should be on the front page like all the README files on GitHub have an install or usages section.

2. Help users find the current docs for matchers and configuration.
Just try searching for a matcher or a specific configuration it just doe not work (At least not as I expect it to). And try to read the docs like a noob. They are not detailed enough to help noobs or users new to some of the concepts. Ther should be a clear list of matchers and a way to filter or search them. Maybe a cookbook on how to use some of the more advanced matcher (asymmetricMatch).

3. Direct you in the right direction if you have trouble working with jasmine (Not solve all the worlds trouble)
There's a link at the top to GitHub but what about where to post user questions like a forum etc.... Wheres the jasmine community?

4. Other docs that must be there but are of lesser importance.
They seem to be the main focus of the current docs. It is supporting way too many versions. It is easy to upgrade to the next version of jasmine so there should be no reason to support so many versions of the docs.

Ther are a lot of good layouts/doc projects out there that have solved most of these issues and one of them could be borrowed and modified to accomplish this.

Also not having the docs on their own and always have to extract them from the code base is probably hindering the development of the docs. Not saying it wasn't a great ides at one point.

Sorry for the rant but I really would like of my experience of visiting https://jasmine.github.io/ was as joyfully as my experience working with jasmine.

[cabiamdos]

I have the same exact issue, you look at documentation in 4.6

and you look documentation in 1.3

and it is much more confusing now in 4.6 than in 1.3.
Please come back to the old documentation. Thanks

[rugk]

BTW as it has been indicated docs server different purposes and I can recommend https://diataxis.fr/ for a good explanation what and how. One can (and probably should) separate these.

Anyway, I think the most useful docs site indeed is the tutorial page on https://jasmine.github.io/tutorials/your_first_suite . And I like that quite much! Also, it seems to have monospace code now.
Thing is just:

• It is hard to find - as a page intended for newbies aka newcomers to jasmine.
  Confusingly it is not in the get started tab but in "Documentation" -> "Getting started!" -> "Your first test suite"
  
• Yet alone that "Getting started" is used twice is confusing here. IMHO the simplest solution would indeed be to have another big menu item named "Tutorial[s]" or so where such learning resources are saved.

[sgravrock]

I think Diátaxis is basically the right approach. Some of the other suggestions optimize for one of the four audiences Diátaxis names at the expense of the others. I think those suggestions are valuable input, but they aren't direclty actionable. The challenge with Diátaxis is how to get from here to there. A "big bang" rewrite of the documentation is, realistically, not on the table. It's been on my to-do list for four or five years now and I haven't found the time or focus to take it on. Maybe things will be different post-7.0, but I said the same thing after 5.0 and it didn't happen. I also don't think I could recommend having a contributor take that job on, even if someone was willing and had the necessary skills. The risk of coming out at the end with something that doesn't ship is just too great.

It would be interesting to look for ways to move in that direction incrementally. Are there things that could be done in a few hours (ideally by someone who's not a maintainer), would improve the situation, and wouldn't create a problem even if no further Diátaxis-ization were to happen?

[sgravrock]

As for the old side by side documentation format: I understand the love for it, but it had serious problems even back in the 1.3 days and has aged poorly since then. For it to work well, all of the following need to be true:

• Code and prose are brief
• The height of each section of prose is roughly similar to the height of the corresponding code snippet at any reasonable window width/font size/zoom combination. (See screenshot below for an example of how readability of the code suffers when the prose is too long.)
• Every line of code is short enough to fit alongside the prose, without wrapping or overflowing, at any reasonable window width/font size/zoom combination
• Everything that you're documenting can (and should) be demonstrated with a code snippet.

That worked ok in 1.3 because Jasmine was relatively simple, the docs site only provided a introduction to the core testing API, and the design assumed a wide browser window and relatively decent eyesight. Even if Jasmine had remained as simple as it was in 1.3, the side by side format wouldn't handle today's expectations well.