A documentation for ArmoniK

[Barbapapazes]

Hello,

Actually

Here the state of documentation:

• Some repositories have one, some haven't (so documentation is divided in many places)
• Some repositories use Docfx, some VitePress
• It's not clear on how to contribute to documentation

Docfx can't fit our needs because it is slow, hard to use and hard to customize. Because the DX is terrible, nobody wants to write documentation.

Proposals

To have a better tool urge because without a correct documentation, it will be harder and harder to continue to increase the complexity of ArmoniK.

To solve this major issue, here 3 proposals. First, we must decide how we want to structure our documentation and then, we will discuss about which tools we want to use.

Let's talk about in comments.

Unified documentation in a repository

Because the source of the main website will be private, we can create another repository called docs.<main hostname> which will contain the documentation.

Pros

• Easy to contribute
• One repo, one purpose

Cons

• Separated of the main repository ArmoniK (could also be a pro to manage easily issues and PR)

Unified documentation in the ArmoniK repository

Because ArmoniK is the main repository, it makes sens to have documentation in it under .docs folder.

Pros

• Near the main source

Cons

• Associated to ArmoniK but will contain documentation from other repositories
• Issues and PR for ArmoniK and its docs will be together. This can slow down documentation.

A .docs per repository

Because every ArmoniK repositories have specificity, it could be interesting to have a .docs folder per repository.

Pros

• Documentation is near to each source code
• Maintainers can easily update their own documentation

Cons

• User will have to navigate to every documentation through every repositories
• Issues and PR for .docs and others will be together

[esoubiran-aneo]

Hey @aneoconsulting/armonik, what do you think about this?

[aneojgurhem]

I agree with the issue. We started with documentation in each repository and some on the main. I prefer having doc and code at the same place because we can write and review both at the same time. Adding doc in another repo + pr means that we will not do it.

[jfonseca-aneo]

Thanks for bringing this up, 'm also biased towards a per repository documentation. I'd add that we also need to split the documentation so it targets users and developers separately. We're currently not taking external contributions to the code, but that will arrive soon or later, and we'll need to invest some time in the respective "how to collaborate" guidelines.

Besides the documentation, a sort of blog or step-by-step tutorial will be of great value, I really like for example the approach taken by this library: https://www.dealii.org/developer/doxygen/deal.II/Tutorial.html (I'm not fan of doxygen, its the structure of the tutorials I'd like to bring here )

[esoubiran-aneo]

Seems related to @dbrasseur-aneo comments

[dbrasseur-aneo]

Your point is entirely correct. ArmoniK lacks a well defined doc.
For me, we need to distinguish the User documentation and the Developer documentation.
For the developper one, a doc per repository makes sense:

• Closer to the related code
• Could use automatic documentation from the code
• Changes in one repo only if functions change

For the User though, I think using the ArmoniK repository only will be the best. This repo is supposed to be the "meta" repository (Well, when we will finally move all the infrastructure to the ArmoniK.Infra repo) linking the other repos together by specifying the right versions, with user friendly scripts and automation. It would then be THE reference point for anyone wanting to use ArmoniK, with documentation and installation scripts

That's my 2 cents on the matter

[esoubiran-aneo]

Ok, sound nice! I think we must define more what is called a "user" and a "developer".

Definitions could be:

• Developer, will create code pushed to a repo so documentation will explain how things work under the hood
• User, not a developer, will deploy, install, play and run ArmoniK

Is this ok for you?

[dbrasseur-aneo]

Yes, these are the definitions I'm refering to

[ngruelaneo]

I am 100% in agreement with @dbrasseur-aneo. There are a need to separate the user and the developer documentation.
As for the definition, it is a little bit more complex since the users could be different: one will use the GUI, another will want to develop a client in C#, another one in java...

[esoubiran-aneo]

Hello @aneoconsulting/armonik ,

Thanks for comments. After reading them all, I propose this action plan.

Action plan

• Throw away Docfx to create documentation (but still to generate .md from C#
• Use Docus to create every docs
• Start by creating dev and user docs for ArmoniK.Admin.GUI and ArmoniK.Api. This will allow you to see how it works and to see possibilities. (2 weeks max)
• Then, create docs for every repo using Actions and Best Practices.
• End of February, each doc from ArmoniK will be unified.

Of course, there are many side-effects. So How-To-Contribute.md and how to use and start docus will be written.

Why Docus

Docus uses markdown to generate docs. It separates content from form which is a plus to easily update content without touching styles (like html and css).
Based on Vite, it allows content creator to visualize in real-time modification.

And the more important, using a repository for the theme, we will be able to easily share the same theme to every doc (and maintaining only one package).

Is this all ok for you? 🚀

[aneojgurhem]

I'm okay with that.

[ngruelaneo]

Did you try to use the markdown files created by docfx?
But I agree with the plan. We can try Docus.

[ngruelaneo]

I am fixing the pipeline for the docfx installation (which has to be use to create the documentation from the C# file

[aneojgurhem]

thanks !