Features to improve the documentation process

Jponline · June 3, 2020, 1:50pm

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.

github.com

JpOnline/Blog/blob/master/documentation_sprint.md

## I now declare it is opened the documentation week.
**The goal is to have a prototype by the end of the week**

I can see several problems related to that, 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.

When you think about it, you see that documentation is already a solution of a problem, the problem of understanding a code that you are starting to work with.

The code are the **facts**.\
The comments are the **knowledge** imputed by **human**.\
The tool will show you an interpretation, a **point of view**, a way to see the combination of **fact** and **human input**.

> Neo: Do you always look at it encoded?\
> Cypher: You get used to it. I don’t even see the code. All I see is blonde, brunette, redhead.\
> -- Matrix

## Nice to meet you
My name is João Paulo, I love to code and create real solutions for real problems. I love the Clojure programming language and I'm using it for about 2 years to create Progressive Web Apps using Web Components as a Free Lancer.

## The process

This file has been truncated. show original

slifin · June 8, 2020, 3:04pm

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

Jponline · June 9, 2020, 11:32am

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.

Phill · June 13, 2020, 3:39am

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.

system · December 12, 2020, 3:39pm

This topic was automatically closed 182 days after the last reply. New replies are no longer allowed.