In this post I am finally pleased to sum up the last of my experiences releasing Open Source libraries to help launching Selenium WebDriver instances in .NET Core projects.

Whilst actually the last of the posts chronologically in this series I am placing it as post number 1, feel free to skip to the next one and read through before coming back if you want the story in the order that I wrote it.

Writing the code of an Open Source library is only half the problem

Apologies for the lack of posts for a while. As well as giving my first conference keynote talk and coping with the usual challenges of work and life, I am delighted to announce that last week I finally locked down the API changes and released the ‘CI/CD ready’ version 3 of my NetCoreWebDriverFactory and WebDriverFactoryNunitConfig libraries.

The challenge of going live: Support

The simplest solution would be to just say “that’ll do” and release the packages on nuget. Of course if you have ever used a library, you will know that there are two forms of documentation that are the key source of knowledge to anyone solving a problem:

• StackOverflow
• The library’s own documentation

I put them in that order because in reality, you will usually hit up your favourite search engine and ask your question. The more popular libraries often return numerous SO questions above the actually official documentation. Of course for a brand new library that will not be the case as it is unlikely that anyone will have asked there.

In reality, if a developer trying out your code cannot work out how to use it within a few minutes, they will soon move on to the next idea. So having “enough” documentation to get them started is essential.

Types of Documentation

As I was finalising my code I came across What nobody tells you about documentation. This identifies 4 types of documentation and the roles that they perform:

• Tutorials: focused on learning for beginners
• How to guides: Using the libary to solve specific problems for implementers
• Explanation: Giving background and context
• Reference: Accurate and complete information

Tutorial

I don’t plan on taking things right back to basics yet, but I may try a video guide or similar later. In the meantime I have added some MVP test projects on the wiki to help out someone just making their first steps in .NET Core.

How to guide

I have a little more to add here; particularly around which concrete implementations to use for different use cases when setting up for a CI/CD pipeline. The source code for the included ServiceCollectionFactory should be a decent guide to start from.

Explanation

Well this is well covered fortunately by my documenting the challenges faced in this series of blog posts. It certainly adds context.

Reference

This has caused me the longest delay to work out. Automating API documentation and working out where to post it has been quite a challenge.

In the end I settled on using Doxygen to generate my documentation. My original plan was to generate the documentation and check it in to the source code repository. I could then easily use GitHub Pages to serve up the pages.

The problems with this approach

I had two concerns about this that made me change my mind however.

• The generated code will always be of the last version I checked in. I guess that should effectively mean the current release version. I want to be able to maintain the documentation for previous versions as I release new ones.
• The generated code includes javascript modules licensed under the GPL. As I want the library, including the sources, to be free from any possibility of a legal licensing use challenge.

My solution

I felt that the only approach was to use a separate user based GitHub Pages repository to store the documentation. I can then generate new docs for each version and add them rather than replacing. You can access version 3 docs here.

Only the Doxyfile xml definition file needs to be in our main source control repository.

I also hacked together an index page to signpost documentation and other web content that might be helpful.

So all done?

In short yes!:

✓ Code version set to v3.0.0 (release) and checked in

✓ CI build complete and Unit tests passed

System tests passed on:

✓ .NET Core 2.1 on Windows 10

✓ .NET Core 2.1 on Ubuntu linux 18.04 LTS

✓ .NET Core 2.1 on MacOs Mojave

✓ .NET Framework 4.7.2 on Windows 10

✓ Pull Request into master branch completed

✓ Docs proofread and checked into docs repository

✓ Version 3.0.0 of the NetCoreWebDriverFactory and WebDriverFactoryNunitConfig libraries released to nuget.org for your free and unrestricted use on June 19 2019.

In Summary

Progress made:

• Version 3.0.0 full release completed with documentation online. WooHoo!

Lessons learnt:

• Documentation is in many ways harder than coding (and way less fun!)
• Tutorials; How to guides; Explanation and Reference sections are required for effective use.
• Doxygen can be used to automate the generation of API documentation
• GitHub pages is a very simple means to host your generated API documentation

A reminder:

If you want to ask me a question, Twitter is undoubtedly the fastest place to get a response: My Username is @AlexanderOnTest so I am easy to find. My DMs are always open for questions, and I publicise my new blog posts there too.

Series Navigation

Starting to build a (new) .net Core PageFactory >>