Best Practices for building an EA Org?

[Alberto]

Does anyone have or know of any comprehensive set of best practices for building an EA team around Archi?

I've been working with Archi for a while as a solo modeler and am considering getting ArchiMate certified. I'm also thinking about designing a modeling workshop for my BA and Solution Architects colleagues, hopefully to transition our currently disjointed modeling practices into a more structured ArchiMate-based approach, and possibly build an EA practice around it.

I'm aware of resources like Gerben Wierda's Mastering ArchiMate and Eero Hosiaisluoma's ArchiMate Cookbook for diagramming patterns, but I'm looking for a more comprehensive set of best practices beyond that. Specifically, I'm interested in guidance on:

Naming Conventions for Views/Elements/Relationships/Specializations, jArchi Scripts for streamlined modeling workflows (e.g. adding legends), modeling current state and future state, managing models (e.g. single and multiple models, collaborating strategies), using coArchi effectively with multiple users, etc...

I'd really like to know if there is a comprehensive set of best practices that this community can recommend, and preferably one that is framework agnostic, it would be greatly appreciated!

[Jean-Baptiste Sarrodie]

Hi,

I'm not aware of any open or shared best practices. Of course I do have almost everything you mentioned but that's mostly for internal use at the moment. I guess I could make a big part of this public (that was the plan when I started working on the ArchiMate 101 on the ArchiMate Community).

My main issue is the time needed to curate this material, but if we make it a collaborative effort, then we might be able to have a first draft before this summer.

Maybe we should create a GitHub repository for that purpose to exchange ideas and content.

Regards,

JB

[Alberto]

We could, but as a personal preference, I'd like to keep the conversation here for now as I think this is an open and broad topic. Also, I find this forum has a lot more history than the ArchiMate Community forum (probably because this is where it all started for me), so we can always refer to past conversations.  For example, this topic about "AS-IS, Transition, TO-BE" has some good nuggets of wisdom that are great. I just don't know how to best structure the the topic, so perhaps we can start with that?

[Jean-Baptiste Sarrodie]

Hi,

I'd like to keep the conversation here for now as I think this is an open and broad topic

My main issue is that such topic can't be covered by a single post as it will quickly become a multi-pages documents. Thus a wiki-like approach seems the best to co-edit it.

Also, I find this forum has a lot more history than the ArchiMate Community forum

By "creating a GitHub repository" I was not referring to the ArchiMate Community but Archi Contribs (where non official plugins and scripts are shared).

Maybe we can start defining what the table of content would look like, find some already existing discussions on these topics, and then switch to a wiki.

Regards,

JB

[FredFlintstone]

Hi,

being a regular reader and a frequent user of Archi I have for long been looking for where I could help this great work. Guess that I just found it :-)

Suggestions for topics in arbitrary order:
- Model vs models
- Model structure
- Publishing / sharing
- Utilizing properties
- Model navigation
- Drilling views (relating elements from one view to a second view)
- Prying view metadata to view
- Keeping metadata updated
- Integrating model data with external sources
- Single user - multiple users (coArchi)
- JArchi scripting - many sources

Sorry if the level of detail is varying, some might well be subsections.

Let me know if you find that a extra set of hands an a keyboard is needed.

[Alexis_H]

Hi,

Having a few years of practice of Archi in a collaborative use-case, I'd be more than happy to share (and learn !) with others the best-practices we can derive from our experiences.

@FredFlintstone list of topics are all relevant ones.

I would have added a few others where I can share some thoughts:
- Meta-model (restricting or not)
- coArchi : branch strategies
- Model sanity check / cleanup process
- View templating
- EA + SA model(s)

Regards,
Alexis

[FredFlintstone]

Just picking up from you JB

By "creating a GitHub repository" I was not referring to the ArchiMate Community but Archi Contribs (where non official plugins and scripts are shared).

Maybe we can start defining what the table of content would look like, find some already existing discussions on these topics, and then switch to a wiki.

Would it be that we could create a project repository on https://github.com/archimatetool where the work could be conducted. Keeping the discussion on subjects and details in a section of the forum or in the GitHub Issue tracker?

Like you write, the Wiki could be a god place for the material. Alternative could it be the code base with the content and structure in markdown or rst format. This way the content of the material could be forked and worked on local. What kind of challenges this imposes I'm not sure this is though where my knowledge of what can be done using GitHub ends. But having the option of compiling a printable output format from the content could be an alternative to having it on the web.

Just a few cents of thought.

[Jean-Baptiste Sarrodie]

Hi,

Not on https://github.com/archimatetool but on https://github.com/archi-contribs.

Alternative could it be the code base with the content and structure in markdown or rst format. This way the content of the material could be forked and worked on local.

Yes, that's an option too, but it really depends on the potential contributors and their initial knowledge of documentation systems. I am used to 3 level of documentation management for such use-case:
- Wiki pages: that's the easiest way for people to contribute, but the content can be read only through the GitHub/GitLab/Whatever user interface, which does not help to focus on the content.
- Markdown content using https://docsify.js.org. That's my favorite because markdown is easy to author and we can read the content through a real website (hosted as a GitHub page, but without having to "compile" it).
- Asciidoc content with an automated publication pipeline. That's what I use for the ArchiMate 101. That's harder top setup and use, but asciidoc is better for managing big documents that can be "compiled" as website or books.

Regards,

JB

[Alberto]

OK, I've published a rough draft on my GitHub.

https://github.com/AlbertoDMendoza/ArchiMateBestPractices

It desperately needs an editor to check for flow and consistency.  Some parts still need expanding, so consider it a starting point.

Feel free to review, comment, suggest, request, or altogether ignore. 

[FredFlintstone]

Great initial work Alberto

I'w cloned your repo, will spend a bit of eastern time adding stuff. I'll submit a PR one I have something that you can look at.

As for keeping everything in one .md file, I'm not sure that it will scale. But let not that be an issue right now. Refactoring can always be done :-)