Rahul gives unsolicited advice

Words aren't always enough. I was trying to digest the  Keycloak documentation on securing applications  and after spending eight hours on that page, I finally realized that I was trying to construct diagrams in my head using the words. I was trying to construct the control flow in my head using the words on that page. And that is almost always a lossy transmission of information. I believe that a few sequence diagrams ( uml , mermaid ) can do wonders in that documentation, helping both people who need words and those who need images. And the verbal people can communicate with the visual people using the images and the text! There's a dearth of diagrams in software project documentation. You could respond by telling me that most software projects don't even have documentation so expecting diagrams is a stretch. To that, I say that accepting diagrams as documentation might help address the issue. Contributors might not implicitly know that diagrams are acceptable contributio...

If you write software, you need to start maintaining Architecture Decision Records (ADRs). ADRs roughly fall into the category of Developer Documentation. They aren't aimed at the Users of the software. Instead, they are aimed at the developers and maintainers of the software. They usually contain information about the layout of the package and what the code does. ADRs, in this context, are an absolute necessity. By definition, ADRs are simply a Record of a Decision that has an impact of the Architecture of the application. In fact, Any meaningful technical decision made in a software project, irrespective of whether it has an impact on the architecture of the application, needs to be documented. I first came across ADRs in Chapter 17 of Fundamentals of Software Architecture book. A few of us (at Enthought ) read this book earlier in the year and ADRs are one of the things that we took away from the book. You can find more information on ADRs here and here . Here's what the f...

The title is chock full of jargon. Let me break it down. API stands for Application Programming Interface. An API is the user-facing part of a software package. For example, if you use the "numpy" package, "numpy.array" is an API. And APIs need to be documented. A single API can produce different results depending on the inputs so documenting the full capabilities of an API is important. Jupyter Book  is a new tool in the Scientific Python community to create and upload documentation easily. The community as a whole seems to be working towards better documenting their projects and some have chosen to go with Jupyter Book instead of relying on Sphinx. I personally don't know why the community felt the need to move away from vanilla rst ( reStructureText ) and Sphinx . One of the advantages of Sphinx is the fact that API documentation for the package can be created automatically (using sphinx-apidoc ) and the API docs can be included in the user-facing documentati...