Hi Mark, The documentation that is already been published, has been designed to add value to your existing documentation.
The example in this section: http://tomcat.apache.org/tomcat-8.5-doc/realm-howto.html#Example_Application, has been visualised in these dashboards: https://design.codelytics.io/tomcat/security-login-form and https://design.codelytics.io/tomcat/security-login. The example in this section: http://tomcat.apache.org/tomcat-9.0-doc/jndi-datasource-examples-howto.html#MySQL_DBCP_Example, has been visualised with these dashboards: https://design.codelytics.io/tomcat/jdbc-initialisation and https://design.codelytics.io/tomcat/jdbc-query. We could possibly show an image of the sequence diagram at the respective locations, which when clicked, would open a new tab with the full visualisation. The reader could explore the visualisation to get a more though understanding of the topic at hand. Alternatively a more integrated approach might be to open an embedded iFrame, and when the user had finished, the user could close the iFrame and continue reading. If we integrated those two pieces and you found that users engaged with this content, then maybe we could extend it out to cover different areas. Regards Adrian. On Wed, Jun 7, 2017 at 7:45 AM, Mark Thomas <ma...@apache.org> wrote: > On 03/06/17 04:00, Adrian Bartlett wrote: > > Thanks for your feedback Mark. Its been a while, but I made some updates > to > > address your comments. And the updated dashboards are here: > > * https://design.codelytics.io/tomcat/security-login-form > > * https://design.codelytics.io/tomcat/security-login > > > > If I was to work with one of Tomcat's expert/senior contributors, we > could > > document the entire Tomcat architecture. An example of a dashboard more > at > > the architectural level is here: > > https://design.codelytics.io/tomcat/jdbc-query. Notice in the sequence > > diagram how the objects have been grouped into packages, which enables a > > higher level of abstraction at the architectural level. > > > > This documentation would give new contributors the ability: > > * To get up to speed quickly on the inner workings of Tomcat, and > > contributing sooner > > * To better align their work with Tomcat's existing architecture > > > > Users could also read the documentation to gain a greater understanding > of > > Tomcat, and improved ability to self serve. > > > > We could tie the documentation generation into your CI/CD system, so the > > documentation was always up to date and hosted on your own servers. > > > > If you think this can add value, send through an email of someone > > interested in helping. And we can go about capturing Tomcat's important > > concepts. > > I'm probably one of the worst people to ask if this would be useful > since I'm pretty familiar with most of the Tomcat code base. Some input > from people newer to Tomcat and still finding their way around some > areas would be better placed to point your efforts in the most useful > direction. > > Mark > > > > > > I have been using Tomcat since 1999 and would be tickled pink if I could > > help out in this way. > > > > > > > > On Fri, Mar 10, 2017 at 10:18 PM, Mark Thomas <ma...@apache.org> wrote: > > > >> On 10/03/17 11:19, Adrian Bartlett wrote: > >>> Hi All, > >>> > >>> I documented the: */jsp/security/protected/index.html*, example that > >>> comes bundled with Tomcat. It is documented using Sequence Diagrams and > >>> Class Diagrams in the following two dashboards: > >>> https://design.codelytics.io/?dashboardId=tomcat.cms.login_form > >>> https://design.codelytics.io/?dashboardId=tomcat.cms.login > >>> > >>> If you feel that this type of documentation is useful for Tomcat users > >> and > >>> developers. I can document other aspects of Tomcat, like Realms, > >> Connection > >>> Pooling, Valves etc. > >> > >> Anything that helps users understand how things like this work is good. > >> > >> I found the UI a little clunky and my personal preference is to see more > >> information on the screen at once. > >> > >> You need to include part 2 of the security constraint in the excerpt > >> from web.xml in the intro. > >> > >> I suggest asking for feedback on the users list to see which areas are > >> of greatest interest. > >> > >> Kind regards, > >> > >> Mark > >> > >> > >> --------------------------------------------------------------------- > >> To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org > >> For additional commands, e-mail: dev-h...@tomcat.apache.org > >> > >> > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org > For additional commands, e-mail: dev-h...@tomcat.apache.org > >
