Proposal: documentation overhaul and hostnames

[mroderick]

I think it's time for a major overhaul of the documentation of the sinon package, to make it easier to understand.

I'd like all our projects to have good documentation. The volume and quality of documentation for the minor projects vary considerably.

I think that if we create an example of how we would like the documentation to end up, then we can recruit contributors to help speed up the work ... and in the process also get more regular contributors into the organisation.

Desired end state

• Each part of the public API is documented on it's own page
  • Easy to link to
  • We can add more examples per function
  • Examples are runnable pieces of code that have their own tests
• Easy for contributors to improve documentation
  • Only one set of documentation, not a set per released version (which has become a bit of burden)
  • Maybe: use a Docker container to make it a one minute task to start contributing
  • Changes to documentation becomes visible after merging (currently that only happens after release)
• Each project has good API documentation
• Re-usable Jekyll theme, that can be used by all our projects (see How to Create and Publish a Jekyll Theme Gem)
  • Modern browser support (we're targeting developers, they keep their browsers up to date)
    • Evergreen browsers, last two versions
    • Prefer web standards over proprietary solutions: CSS Variables instead of SASS
    • Prefer system fonts over custom fonts
    • No JavaScript frameworks
    • Progressive Enhancement, pages should work without JavaScript

Hostnames

In line with the effort to improve documentation for our projects, I have been thinking about adding more hostnames or sites.

• https://sinonjs.org — jumpstation or hub for all the active projects, tutorials, etc.
• https://lolex.sinonjs.org — API documentation
• https://nise.sinonjs.org — API documentation
• https://referee.sinonjs.org — API documentation
• https://sinon.sinonjs.org — API documentation
• https://sinon-test.sinonjs.org — API documentation

Main site

For the main site, I think we should stick with Jekyll, for a few reasons:

• server side rendering
• directly supported by GitHub Pages
• large community
• mature project (MkDocs, I've since learned, is not)

However, getting Jekyll running locally can be a bit of a challenge, which probably deters some contributors. If we make a Docker container for running the documentation site locally, it will be as easy as starting that container and editing Markdown files. GitHub Pages can do the heavy lifting of publishing, once docs are merged to master (as we do now).

API sites

For the API documentation, we could consider using JSDoc, as that can be verified using ESLint and other static analysis tools.

We could take an approach like: convert JSDoc to Markdown, and use GitHub Pages via Jekyll to publish it.

Related: https://github.com/jsdoc2md/jsdoc-to-markdown

Runnable examples with tests

For the main site with tutorials, it should be easy enough to integrate examples as runnable, testable fragments.

If we generate API documentation sites from JSDoc, that might be a bit of a challenge to do that in an elegant way without seriously bloating and complicating the source code.

[mantoni]

Makes a lot of sense to me. Again, nice and consistent with GitHub (and the npm namespace). 👍

[mgred]

Hey @mroderick Is this still a relevant topic? I would like to contribute if so. The minor projects seem to be migrated to MkDocs already. Should that be done for the major one as well?

[mroderick]

Is this still a relevant topic? I would like to contribute if so.

Contributions would be most welcome

The minor projects seem to be migrated to MkDocs already. Should that be done for the major one as well?

After using MkDocs in a work project, I've learned that it is not as mature/elegant as I'd hoped for. It's fine for the smaller projects, but so would a good README.md be.

I will try to update this issue with my thoughts on what the goals of our new documentation site should do. If you have time, please post tips, ideas, links to inspiration or examples of great library documentation.

[mgred]

Alright, sounds good.

As an inspiration so far, check out:

• Docusaurus
  • Babeljs - https://babeljs.io/docs/en/
  • Jest - https://jestjs.io/docs/en/getting-started
• Docsify
  • Showcase - https://docsify.js.org/#/awesome?id=showcase
• Asciidoctor

[mroderick]

I've updated the original post with more thoughts. Feedback and suggestions welcome

[mgred]

Use a Docker container to make it a one minute task to start contributing

That's a nice idea. I created a branch that includes a docker-compose file to serve the site from a container using a simple jekyll image as a first attempt. You can run:

npm run serve-docs

Note: You need docker and docker-compose installed.

I also updated the Documentation to point that out.

Only a single documentation base, not one per version

That definitely simplifies development and contribution. But having a decent and beautiful documentation for every release (version) is a quite luxurious thing somehow :)

For the API documentation, we could consider using JSDoc, as that can be verified using ESLint and other static analysis tools.

:+1: This is also good to document types of parameters and functions properly in source code and documentation which might help developers understand it better.

[mroderick]

I had a look around for possible solutions, and came across GitBook. Does anyone have any experience with it?

[mgred]

Unfortunately, I don't

[fatso83]

Heard good things about GitBook, but I don't have any experience using it.

We could take an approach like: convert JSDoc to Markdown, and use GitHub Pages to publish it.

Seems like a very unnecessary step. Jekyll converts markdown to html, and if that is the end result we might as well use one of the many existing jsdoc tools that produce html. High probability that we have much more control over the end result then the jsdoc -> markdown -> html route.

having a decent and beautiful documentation for every release (version) is a quite luxurious thing somehow :)

@mgred We could still have that. On the topic of GitBook (which is a stable project with many years of battle testing), they seem to have a pretty nice way of handling multi-version docs.

[mgred]

@fatso83 I created a test account for the project on gitbooks a couple of days ago, I hadn't had the time to play around much. I can send an invitation link to the group if you want to have a look?!

[fatso83]

Sure, but I don't have any time allotted right now.

[mroderick]

I've updated the description a bit with details about creating a re-usable Jekyll theme as a gem

[mroderick]

This is my current favourite: https://www.11ty.io

[mroderick]

Inspiration: https://testing-library.com/docs/intro

[mantoni]

11ty is also my current favorite.

[MartinMuzatko]

My current tech stack:

• vuepress - Static site generator / server side rendering with client-side
• netlify - automatic deploys, pull request previews
• optionally: forestry - WYSIWYG for git hosted markdown documentations or websites

I have successfully implemented this stack for various open source projects: https://strapi.io/documentation https://inexor.org/ https://docs.exa.sicon.io/ (WIP)

10,000€ seems like an unrealistic goal. The community should be willing to contribute one in a cooperative effort. I could contribute in the tech stack I am familiar with, with your requirements. But it should be an ongoing community effort to maintain it (the edit this page on github links on the bottom of the pages make this more inviting for first-timers :)

[mroderick]

@MartinMuzatko thank you for your comments.

10,000€ seems like an unrealistic goal.

Considering how little backing it's gotten so far, I agree, it doesn't look very realistic.

Sinon is nearly 10 years old. It is in use by many fortune 500 companies and most major tech companies in one form or another. It gets ~100M downloads a year.

But, it doesn't have the glamour of some of the most popular projects on Open Collective, so it doesn't attract the same kind of financial backing.

The community should be willing to contribute one in a cooperative effort.

That would be nice :)

I could contribute in the tech stack I am familiar with, with your requirements.

We are leaning towards using 11ty and Netlify. Your contributions to the effort would be most welcome.

But it should be an ongoing community effort to maintain it (the edit this page on github links on the bottom of the pages make this more inviting for first-timers :)

I agree.

We're continually trying to make it easier for newcomers to the Sinon community to contribute to making things better.

Since we moved the documentation into this repository and use Markdown instead of Restructured Text there has been many more contributions. Moving from Jekyll to 11ty means that contributors won't need to configure Ruby, when they want to run the site locally.