One thing most programmers dislike doing is writing documentation. It's generally seen as a mundane task that you’re forced to do, a sort of chore in software development. It often feels like a waste of time, that could be used coding something new for your web app or other project. Instead that time has to be used on explaining that code to others. Everyone still does do it though, as it is basically the gateway to your project for everyone else. So it is usually worth to sacrifice some time working on one to make things easier for those who might be interested in what you’re working on.
Not a waste of time
A well written and detailed documentation can be quite a draw, that’s why tech giants like Google and Facebook do work on those for the projects they take under their wing. If you’re looking for inspiration you can check the documentation for Django to see an example of a particularly well done one. Even if you’re not too keen on writing it now it can save you some headaches down the road when you want to interest others in your web app, library, framework or whatever it is you're working on. While some think documentation is insignificant it actually does play a large role especially for things with a steep learning curve or a lot of complexity. For various tools it can even be make or break, as when it comes to application development, most devs prefer to start out with a clear picture instead of working out everything themselves. It's also best to start making documentation gradually so that it grows with your project. Otherwise you can end up with a ton of work somewhere down the line, needing to document everything from scratch for a project that has grown quite large.
Magidoc
Fortunately there are some tools that can help you create documentation. Yes they wont do literally all the work for you (at least yet) but since the priority is to get it done as fast as possible, any tool that speeds that up should be a boon. One such tool is Magidoc, it's a static documentation auto-generator designed for GraphQL APIs and created using Svelte. Since we’re interested in getting done with documentation as quickly as possible let’s simply check out the features:
- fast and simple: Magidoc works out of the box and can generate documentation for each query, type, subscription and mutation in your GraphQL API, by simply using your schema or a live endpoint via an introspection query.
- easily customizable: Magidoc uses a simple JavaScript configuration file which lets you customize it to your heart's content.
- markdown support: Magidoc supports markdown so formatting your documentation is as easy as writing a forum post. It also supports advanced markdown features so if you need tables or inline HTML you can also work with that.
- useful plugins: Magidoc also has a Svelte PrismJS wrapper and a markdown parser that renders into Svelte components and supports GitHub Flavored Markdown for those wanting to make their documentation a bit more fancy.
Apprecieate the help
As you can see the approach is quick and to the point, you use the defaults and easily get basic documentation which outlines what your API is about and you can work on the configuration and markdown to add more things and make it look nicer. How much you want to spend on that is entirely up to you, some will be completely fine with the basic documentation and glad to have it over with and others will like to fiddle around a bit more. The key point after all is making writing documentation less of a chore, which it definitely does. Its also only a couple months old and being constantly worked on so you can look out for additional features down the line. If you're not interested in that, it does a bunch of things out of the box already, so if you just want to be done with writing documentation asap this will help you get a quick start with that.