Hi Benoit,
Thank you for giving this so much thought. (By the way, I am very sorry that I have been less available these days, and will continue to be so for the next few weeks, but I will still try to contribute to this as much as possible.) > I am making good progress on Antora documentation migration for the > Distributed Server, only a couple of pages are left. Cool! I will try to take some time today to comment more thoroughly, likely in the form of a PR. > [...] I propose to retire the maven-doc plugin, and migrate the > javadoc that exist today as Antora Documentation. I am happy to spend time looking into integrating with Javadoc. I recall reading in the Antora manual that since it reads from the git repository, we can insert actual code snippets and javadoc into the documentation. I remember this because I thought it was a very cool feature. However, I have not yet looked into it in any detail so I can’t say any more at this time. If I can, I will try to take a look today. > Also, now that I almost finished the Distributed server documentation, I > start thinking of my next step: documenting the other servers. There is already a PR outstanding for the Basic Server, but it is still in draft mode because I am not yet done: —> https://github.com/apache/james-project/pull/206 Regarding the Extendable Server, I am currently trying to run it and use it so I can understand it. I have managed to get the system compiling and can finally run in debug mode in IntelliJ, but because I have never used this IDE before, my progress is slow. 😅 I have filed a few issues to help me make progress. Maybe I’ll bump those since it is easy for them to get lost (or if you have a suggestion for a better way for me to communicate my issues, I will follow your suggestion). Once I can understand the Extendable Server better, I am planning on writing about it. Of course, the concepts for these servers are based on what is in the “Concepts” section, which still has many, many holes. > I believe we should keep documentation writing centralize to ease its > maintenance > while keeping each server documentation complete for the reader path to > be straightforward. I am not quite sure I understand what you mean by this point. Regarding Antora includes and such, yes you are right: we should definitely use these when appropriate. I am also happy that you are thinking about this from the reader’s perspective. We also have to remember that “reader” can be one of: • User • Operator • Integrator • Developer and the docs should be geared toward whichever role the reader happens to be playing. Cheers, =David --------------------------------------------------------------------- To unsubscribe, e-mail: server-dev-unsubscr...@james.apache.org For additional commands, e-mail: server-dev-h...@james.apache.org
