Jasmine Web Starter

Over the last few years we have seen software growth like nothing before, just about every aspect of life involves software now.

This now poses the challenge to companies of how to keep up to date Documentation in front of the customer. As there is nothing worse than heading to the doc section and finding out of date information, and even worse finding that you have to download an extremely large PDF just to find out how to change a few settings or values.

Publishing a PDF to the web sure is one way to put manuals/documentation online, but is it that great for the user? Plus how much bandwidth is used to server that large PDF over the year? It's going to add up! Sure you may have a process to update the PDF and publish it to the web, but one of the keys things today is to be able to update the documentation with each release of the software product, which maybe shipping with a 3 or 4 week cycle!

Also how do you handle software patches another PDF? In which case the user has to download the full PDF, plus download a patch release PDF which really isn't ideal for anyone.

But it really doesn't need to be this way today, so lets explore.

Markdown, Repositories & Doc Builders

What if the documentation could be written in Markdown and stored within a Git repository giving us full version control. Then we can use a doc's builder to apply the theme to them, and add all the extra stuff a website needs like nav and footer details. From here you would have a CI/CD pipeline to hold approvals and deploy to the live website multiple times a day.

The software engineering team can now submit a pull request to update the features that they have just worked on which the doc authors can then approve for publishing. Now what would happen if you scaled this to your users and took open sourced pull requests updates too. How big has your docs authoring team now become?

Then maybe the quality and speed of updates to your doc's will become a competitive feature against your competition.

Well that all sounds great but is it going to cost an arm and a leg?

Cost of change

Sure there's always a cost to changing processes which is why you are always looking for a return, so what might that be?

Moving to write Markdown does require some training but its quite straight forward to learn with plenty of free resources available across the web. You can even find some on our Introduction to Markdown page.

Choosing a doc's builder

Then you'll need to choose a doc's builder, we're only going to talk about two of them today, but there are many more to choose from depending on what programming languages you know or are using. This interesting page on the Starlight website contains a few others to look at starlight.astro.build/environmental-impact/

The two we are going to call out are widely used for doc sections across the web today.

Docusaurus by Facebook. Is released under a MIT license Docusaurus allows you to use JavaScript or TypeScript for configuration.

Starlight Powered by Astro. Starlight is also released under a MIT License.

Both of these support turning Markdown into HTML websites.

To use either of these you do need to have basic Node.js knowledge to install and run the processes, but for the configuration you will need to have basic knowledge of JavaScript or TypeScript for Docusaurus, and Astro knowledge for Starlight.

The great news is both vendors offer good documentation to help you get started (now there a surprise!).

A good way to kick the tyres and try these out is to use a GitHub Codespace, Codesandbox or StackBlitz, Docusaurus offers a guide to using Codesandbox or StackBlitz at docusaurus.io/docs/playground.

Hosting

So once you have a repository set up and the doc build configured you can then use GitHub Actions for publishing to Hosting.

Depending on where you are going to host your doc's website you might find a tailored example action file, or you will need to use the action template and modify it to fit your needs.

The hosting requirement is not that demanding for a doc's site as any modern static hosting will do, an added advantage is to use one that already has a CDN (Content Management System) inbuilt as docs websites can get image heavy depending how you structure your docs.

Version Control

So now you have a centrally controlled point for docs, that is version controlled and then publishes to Hosting on demand. Another great feature we haven't mentioned yet is this offers great mobile support for those users that happen to be using a phone to read your documentation, so happy users all round that you might have just persuaded to be a repeat customers.

Maybe the next tasks could be adding an action to optimize images before they are published, adding testing with Playwright or to add interactive coding examples or API (Application Programming Interface) playgrounds. We have some plans to publish examples of these type of additions next year.

Let us know if you are interested and which type of example you would be more interested in, reach out using our Contact form.

Interaction

But if you can't wait then take a look at Embedding Codepen, Codesandbox, StackBlizt, Replit, INDIEPEN or LiveCodes which you can self host. Alternatively if you want a fully interactive environment take a look at Sandpack by Codesandbox or TutorialKit by StackBlizt. If you do start using one of the above we would very keen to hear about it, lets us know using our Contact page.

Automation

We have talked a lot about GitHub Actions so we can hear you thinking "how much will that cost me?" Depending on your GitHub account you get quite a good quota free for both storage and use, after that its a chargeable item but the price is quite controllable and straight forward. For more pricing information check out About billing for GitHub Actions.

Just before we go

All of the doc's builders we covered above can also be used to make great internal staff or quality manuals for day to day use within your own company. Keeping everybody on the same page showing the quality and responses the business is expecting from all staff. You could even build in a simple way to collect feedback, updates or additions.

Always happy to help

I hope this has given you some idea of what is available and maybe made you think twice about just publishing a PDF but if you think we have missed something out or you would like more information about some part of this tip then reach out using our Contact form. We would be very happy to apply updates here.