Docs Offer

[parker-codes]

Hello,

I am a regular user of Carbon through Laravel. I wanted to offer to redo the docs site through Gatsby if you're interested. It works very well for docs for a number of reasons:

• compiles into static files for cheaper hosting (free on Netlify)
• load times are as fast as possible
• would be a PWA (caching and installable)

On top of that, I have some ideas for aesthetics that you may like.

Let me know what you think!

Parker McMullin

[kylekatarnls]

Hello,

I have to consider it wisely, we yet have a lot of automated features in our doc we do not want to lose for load time or design improvement.

I have to update the documentation very often and I do not wish to take more time in it without a consequent benefit for the doc.

For exemple following features we have must be kept:

• Auto-deploy via gh-pages GIT branch
• Typing code to get a result example
• Reference menu (double-click on a method to see its details)
• Run live editor on click of code snippets
• Affix menu
• Changelog extracted from GitHub
• Travis unit test to check every method is documented
• Loop templating (for example: lists of supported languages and supported isoFormat are generated automatically based on array results we get from the current state of Carbon), see https://github.com/briannesbitt/Carbon/blob/gh-pages/docs/index.src.html#L701 for more details

Note that our doc is already compiled into static files (and hosted on a static hosting). And can be edited by anyone using those instructions https://carbon.nesbot.com/contribute/

I already used Gatsby and I'm not sure to understand why it would be somehow different in caching or installability because it's a PWA.

But I'm very interested in learning more about it and see how it can help Carbon.

[parker-codes]

Thanks for your quick reply. I think that some of those are already baked into something like Gatsby, though it is nice to see that your workflow is so tightly integrated. This is more than I had initially thought.

This all came about because my initial load times for the docs was very slow. I see that consecutive requests are sped up from the caching.

I was only hoping to fulfill a need, but since you already have much of this in place, you can disregard. :)

A note on how a PWA could help - many other docs sites I use are PWAs which let me have them installed on my phone and works offline.

[kylekatarnls]

I do not want to throw the baby with the bath water. I would gladly evolve to shiny new stuff if I'm sure existing features could still be available with equivalent ease of maintenance.

[parker-codes]

I completely understand.