Features to improve the documentation process

The goal is to have a prototype by the end of the week

I can see several problems related to the documentation. When I get to work in big projects that exists for a long time, I usually spend a lot of energy to understand what is happening, what are the main elements, the domain entities.

It might be because documentation gets unsynced with the code, but could be something else and what I’m going to do is to address this problem and produce a prototype by the end of the week. So if you have time, interest and energy, please contribute with insights. Thank you.

1 Like

This doesn’t address everything mentioned but you maybe interested in: https://github.com/jpmonettas/clograms

1 Like

I updated my github with a solution sketch and some maybe useful ideas.

Would be nice if you let me know what do you think about this features. How can it be approved?

The main ideas are:

  • Using labels to define multiple level of documentation.
  • Run a basic static analysis to identify the function and where are they called to generate a diagram where you can filter elements you want to show/hide.
  • Run this analysis in any language.
  • Warn dev about missing code referenced in doc, maybe it was deleted or it changed the name.
  • Show usage examples of the code (tests) close to the code it tests.

Hi João Paulo,

It is interesting that this week we are also reading “A history of Clojure”.

Interesting & relevant parts include the gearing for dynamic discovery (as opposed to static analysis) and a bunch of design decisions that help a program tell its story so even a human could understand, or on the other hand, help a reader quickly grasp what is going on in a program.