[Doc] Architecture, purpose, usage, and design of the meshery-adapter-library.

[mgfeller]

Current State:

There exists a need for documentation of architecture, purpose and design of the common libraries.

There is little documentation about this now, some of it is in the Meshery Adapters document (drafts, discussions): https://docs.google.com/document/d/1b8JAMzr3Rntu7CudRaYv6r6ccACJONAB5t7ISCaPNuA/edit#heading=h.qgnry4nf3hlv

As of now, two common libraries are worked on: https://github.com/layer5io/meshkit and this one (meshery-adapter-library).

This issue is about meshery-adapter-library.

The use of these libraries by other components than adapter needs to be considered as well.

Desired State:

• Architecture and design document
• Documentation in the code (godoc) of the common libraries
• Where to put new code (and why)
• Dependency hierarchies
• How to use the libraries (and why)
• The documentation should be "just enough", to make it easy for contributors to use and contribute to the libraries

See also

• More clearly roadmap for the project
• Change the name of this repository from gokit to meshkit

[mgfeller]

Some or most of the documentation should be close to the code, as godoc in this case here, possibly also as additional markdown documents with diagrams (which cannot be included in godoc), version controlled plantuml diagrams etc in addition to higher level documentation in the document mentioned above.

A wip PR might be appropriate here, will create one as soon as there is some substance.

Any preferred diagramming solutions? yEd, plantuml, Archi, other? UML or ArchiMate "inspired"? (Not Google Diagrams.)

[Aisuko]

I have no idea on the diagramming solutions, I'm a learner may be @leecalcote have any good idea.

[leecalcote]

Uh-oh... Google Draw or Google Slides have been our go-to tool, primarily given three considerations:

1. Everyone can participate, because everyone has access to the tools.
2. They are free.
3. People can collaborate in real-time on the designs.

[mgfeller]

Glad I asked... not quite unexpected answer :-)

I understand the considerations, of course.

All the tools I mentioned are free, and available on all platforms. PlantUML is nice because it is text based like code, and the generated diagrams are nice. Also, these tools (and others) either have shapes that are appropriate for architecture diagrams, or implement UML or ArchiMate, which we could follow loosely. PlantUML makes it quite easy to collaborate on diagrams the same way as on code.

I think diagrams that document how things are, instead of helping to design an implementation, should be close to the code, i.e. in the repo. There is a bigger chance that they are in sync with the code, because they are more visible. But we can of course export from Google Draw to the repo.

For me, one of the major limitations of Google Draw is that there are only 4 anchor points per shape. It makes it really difficult and takes a lot of time to create good architecture/technical drawings. It's just too basic.

But of course I can also use them.

Could we agree that we follow e.g. UML loosely? Annotate lines and arrows, with verbs such as 'uses', 'realizes' etc. Boxes with stereotypes? Etc?

Would be nice.

[mgfeller]

I think it is more appropriate and clearer if this issue is just about meshery-adapter-library, and I have updated title and description accordingly. Hope that is OK.

The documentation can and probably should of course discuss its relation to https://github.com/layer5io/meshkit.

[mgfeller]

@Aisuko I tried to generate godoc for this module using godoc, unsuccessfully. Is this at all possible? Wasn't able to find much on the internet. Do we have that in some Makefile? Only for this module, if possible, not including everything else.

[Aisuko]

@Aisuko I tried to generate godoc for this module using godoc, unsuccessfully. Is this at all possible? Wasn't able to find much on the internet. Do we have that in some Makefile? Only for this module, if possible, not including everything else.

We do not have the Makefile can generate godoc currently, I'm not sure our project is valid to use godoc, because we did not use go docs before, so there may unknown issue need to fix.

[mgfeller]

Thanks!

Actually, it seems to work, the module's godoc is just burried in all other modules' godoc - it would have been nice to see only the current module's godoc...