Documentation plays a role in GreenDev?

[tonit]

Thinking of re-use, i don't have numbers but experience tells me that well documented software components are more likely to be reused. Can we nail this down? Quantify this? Help with this?

[gadieichhorn]

You need just the right amount of documentation, maybe slightly on the short side. I will give you two examples.

Vertx.io is documentation is perfect. it is full of short information section and many usability examples.

The Spring on the other side is a maze of annotation and configuration option without many examples. Maybe that is why they created spring boot...

The other side of documentation is good community support. Not to provide 5 different channels to the community but 1 place for all experts and novices to meet and exchange ideas and help each other. This covers the gap in the documentation.

OSGi is where you have no documentation for beginners. I don't consider the spec as documentation for developers. Apache Felix has hardly any examples. enRoute is also an example that gets you nowhere as a beginner.

[fpapon]

I think users have to read a bit the OSGi specification to understand the design before using any OSGi framework. https://osgi.org/specification/osgi.cmpn/7.0.0/introduction.html

[tonit]

Thanks @gadieichhorn and @fpapon for beginning the discussion here.

The OSGi specification(s) are probably a landmark for carefully written, cohesive documentation on a living technical piece. But OSGi is also known for having a slow release-pace which allows the technical depth and complexity to sink in. Its not something you adopt "on the go". -as you say, it gets you nowhere as a beginner even with enroute. This resulted in having OSGi dropped in many enterprise projects. Right now i only see it mentioned in IoT related projects on the client side.

Now why do we mention this? For one, there seems to be this urge to adopt and deliver very very fast on the market. I can understand fast-to-market arguments but its strange that also fundamental tech needs to be (as it seems) easy to consume/shallow. Just see how fast you can put together an arbitrary solution in microservice-style using spring boot. It is made for people so they "most likely get it to work, without necessarily understanding much". Does Spring Boot have good documentation for users then? Not really but they have a much more permissive runtime situation (single classloader, static service model) and leverage the fact that its broad adoption leads to many google-able "snippet solutions". I just to say its "copy n paste friendly". Is this good documentation? probably not. But the two aspects outlined here (not very strict, abundance of snippets) get many people somewhere - fast.

GreenDev is (as said in the other ticket about developer experience) a wish to collect arguments, good practices etc in a format that you don't need 20 years of wisdom to get there. And.. package it (naming it is a start) in a way that you can talk about this - rather complex - matter more easily.

Right now, GreenDev carries attributes such as sustainable architecture, give people time to go deep (and not only collect random snippets from the web) etc. Its a moving target. ;)

[ktor]

I mostly work in enterprise environment. Common situation is that documentation is out of date or non existing. Nobody hires technical writers and for developers it is hard to write documentation during the deadline battles. Organizations therefore depend on people/companies that have customer specific knowledge. The knowledge keepers sometimes leave and others must reverse engineer solution or.. it get's rewritten. Not so green.

With that experience the biggest challenge in documentation seems to be: how to write it in small steps as you go and keep it up to date?

As you've highlighted with spring boot. Low entry solutions get used / improved. Same applies to documentation. For reference documentation JavaDoc was a revolution, OpenAPI initiative + API doc generators are used a lot as well. For other types of docs Markdown + various repository solutions is changing the way we use/update documentation. All those solutions are close to the source.

The closer the documentation is to the source the higher the probability, first- that it will get used, second- that it will get updated.

I was researching the topic recently and figured out following technical criteria that enable the documentation to be valid for a long time:

1. is versioned in the same way and place as the source code
2. is easy to read and write in text editor/IDE
3. ASCII format makes it available to generating/publishing automation (like CI servers, repository hosting solutions) and various indexing solutions for easy searching
4. should render nicely for reading/printing

For me personally that currently means combination of following techniques: OpenAPI, JavaDoc, asciidoc, C4

Another very important aspect is scoping. Documentation is a very broad and fuzzy term. It's hard to work on broad and fuzzy things. Easy to work on clear, short pieces that have very specific audience. Well defined beginning and end. Check that ingenious article and video. The proposition is to divide docs into short, well scoped pieces. Small, low entry, format of a building block enables the documentation to be developed gradually.