This is a series on my findings around building open source software online for free. There are many SAAS (Software As A Service) platforms out there and a lot of these are free to use with your open source projects. But not all of these work with C# and .Net. So this series highlights the tools and products out there that work with .Net in different phases of the software development life cycle.
- Build
- Test
- Publish & Deploy
- Documentation <=(We are here)
- Metrics
- Lifecycle Management
Documentation
Whether you had a console app, a GUI, or an Extension Library (shameless plug, oh well), you will want, if not need, documentation. People need to know how to get started and what gotchas to look out for. So here are a few ways to share with your users how to use your awesome tool/app/library.
- Read the Docs
- apiary
- readme
- https://pages.github.com/
Read the Docs
Read The Docs is a documentation service, that can produce Continuous Documentation, by building off of webhooks in your source control, based on a conventional folder of Markdown via MkDocs or reStructuredText with Sphinx, a python documentation engine. They even dogfood their own documentation on their site. You can have active documentation available pointing at stable and latest, as well as versioned from each release using tags. As a bonus, this service is free.
apiary
apiary focuses on API documentation for your services. As well as documenting your contracts, you can show examples of how to use it as well. They also have a mock service based on your definition that anyone using your service can use a test harness, even if you haven’t written your service yet. A DSL called the API Blueprint Language is an adaptation of markdown with some specific mark-up constraints to produce the documentation. apiary is free for one admin + unlimited users, but if you want some of the more advanced features like custom templates, user and role management and other advanced features, you will need to pay $100 a month for up to 50 users, at a minimum. You can even use GitHub at a backing store for your documentation.
readme
readme is another hosted documentation service. This one is only free until you go live, but if your looking for something free for your open source projects, they offer to upgrade you to a Developer Hub tier plan for free (normally $59 a month), which gives you 5 versions, 10 admins, and custom html/css support. Otherwise at $15 a month you get 3 versions and 1 user, and a few less features. readme includes a Markdown editor, crowd-sourcing using User suggestions, GitHub sync and like apiary, it also has the ability for in-line code samples, and an API explorer for users to test your rest APIs.
GitHub Pages
I already mentioned this is terms of a deployment location, but GitHub Pages probably fits better in the documentation section. Using a branch called gh-pages in your repository, you can host the source your documentation in your repository, and have it rendered and hosted by GitHub itself. There are various rendering engines and approaches for this including an automated generator and Jekyll., as well as manually checking in html files.
So there you have a few different options to host different types of documentation. Luckily documentation is pretty language agnostic, so there are plenty of options for .Net Open Source (although I did exclude Inch CI for its lack of .Net support, primarily Ruby, but now with Javascript support). Next up we will look at capturing code metrics to analyse your quality and complexity of your code.