Blogue

Writing Documentation

I consider most of BOLTS technical problems to be solved sufficiently well for now. The only thing that remains to be done until I can release a first beta version is to write documentation. Which proves to be more difficult than expected.

Together with this blog post I will push a polished version of the web page. It is pretty close to what I want, with the exception of the documentation section, which will be in flow for a bit.

I want the documentation for BOLTS to serve one single purpose: To provide people willing to use and contribute to BOLTS with everything they need to do just that. But I struggle with that on several levels.

When I write something (you can check out a few bits and pieces of what I have right now in the documentation hub), I become aware of so many little things, that are self-evident for me, but probably are not for people that have a different background, a different way of working or a different way of thinking. Incorporating and explaining all these things leads to long and complicated texts, which is not what I want.

The second problem is organisation. I roughly know, which topics I want to cover, and I have decided to do that in a tutorial style. But then I feel that some aspects do not fit in this format. It took me a while to figure out, that it feels right to divide everything in documentation for users and documentation for contributors.

Related, but on a different level is that many of the task I want to describe share some of the steps (you should create a git topic branch both when adding a new collection and when creating a drawing), but on the other hand, these steps differ depending on other circumstances. I do not see clearly yet how to organize this complexity.

I will work on this in the next days and hope to make some progress.

To end on a positive note: I had the idea of using the comment system of the blog to add a comment section to each page of documentation. I hope this encourages people to ask questions, propose additions and to generally give feedback to enhance the documentation.

Commentaires