While working on the last sprint’s stories for OCIM, I found myself wishing for more context on why it’s built the way it is.
Some of this context can be found by deep-diving into the git history and JIRA but it feels very much like figuring out where you’re going while only looking at your own feet.
It would be very helpful to have some documentation for the high-level architecture, not just of OCIM but of other applications we develop internally.
Hence, I’d like to start a discussion (apologies if one exists already) on:
whether this is actually desirable, especially considering it doesn’t come for free;
how this could be done; probably everyone has the experience of working on documentation that doesn’t deliver value despite taking considerable effort to make.
My opinion
Obviously, I’m proposing this because I think it’s worthwhile
However, I think the way OpenCraft already works is a good match for this type of procedure:
the written content I’ve seen produced is among the best I’ve seen in any company;
there’s already a very high level of discipline and adherence to the established processes;
the preference for async communication improves the value of long-lived documentation;
OpenEdX already uses ADRs and OEPs, so most if not all members of the team have to work with them.
While I personally like ADRs, especially their emphasis on the context of the decision, I think they make it difficult to get a picture of what the system actually looks like (much like git history).
IMO, there needs to be a companion artifact that describes this current state.
Finally, being a big fan of hypermedia and wikis in general, this would link back to the ADRs, which would then link back to JIRA, allowing one to dig through as much context as needed but keeping the duplication to a minimum.
One of the points in our 2020 Retrospective and 2021 Outlook was to use stronger open source best practices for our internal projects, including better documentation, and I think what you’re saying here is very aligned with that and makes a lot of sense. Even just for internal onboarding of new team members it makes sense, but if we want to see our projects get more traction as open source projects with an active community, it is very important. So +1 from me.
FWIW I wrote up some of this on a recent forum post. Not very discoverable for people exploring the project, I know.
I did read that (I’ll click any link that says DevOps )
In retrospect, maybe I over-emphasized the should we part and forgot to stress the how, which is where most of the differences of opinion will be and where I’d like to see people chip in with their views.
Maybe it’s a bit of a stretch since I’m a newcomer but, ideally, as a result of this our architectural practices would feature more prominently in the handbook: on re-reading the section on Coding Standards and Best Practices I found it does have a mention, although a small one.
I’ve found ADRs to be a good practice. They help you formalise your own thoughts, and I think it would be good to employ something similar in Ocim as well. I definitely faced difficulties understanding Ocim back when I joined, and having some documentation about how everything works would have been great.
I totally second that; I especially like that, because they focus on a single decision, most of the actual text in there is context.
Also, I’ve been growing into the idea that there’s great value in documenting the solutions you considered but did not pick, which is something that fits perfectly in an ADR.
That being said, I haven’t found ADRs by themselves to be satisfactory because, once you start superseding things, it becomes hard to picture the final state (much like understanding a repo’s current state from just looking at the git log); I’ve found that keeping a lightweight description of the system architecture and features helps a lot, especially with a small glossary that describes the domain.
This could then be linked back to the ADRs.
On a final thought/question, is there some standard tooling currently in use for creating diagrams?
I’ve had good experiences using PlantUML, as it’s text based (i.e. good for version control) and usually good enough for high-level diagrams (i.e. it produces weird layouts when there are too many blocks and connections).
Riffing off of @braden 's recent documentation updates, this could be something that would be integrated into the documentation site’s build.
)