However, there was a substantial entry barrier to fully understanding diagrams. As I collaborated with software designers and module developers to produce design docs, I also had to create unified modeling language (UML) diagrams from an architectural view 1 for respective stakeholders.Īs I prepared these documents, I realized diagrams at the design stage are straightforward for writers or readers as architectural views and UML specifications are very clear (Refer to the book called Documenting Software Architecture). The scope of my work included deliverables during the software design stage such as software requirements specifications (SRS), software architecture documents (SAD) and software design documents (SDD). This project carried more weight than others, especially since software design documents were submitted as a basis for product reliability testing. Once I had to write software design documents for automotive electronics, which may lead to critical situations in case of a problem. I'll start with my experience with design documents. Based on my technical writing experiences, I'll elaborate on documents required during software design stage and after implementation. Consequently diagrams included in the documents would vary as well. Maybe not as much as Avi, but I also have a good deal of experience with software architecture diagrams during my career as a technical writer. Documents as a deliverable of software projects vary in type and characteristics, depending on the development process and scope of deployment. Experiences with software architecture diagramming Let me explain by adding my experience to Avi's presentation. Then, Avi moves on to how we can do this. Data: Manage and use the software architecture model as data.Text: Use a text-oriented version control system (in other words, apply the Docs as Code philosophy).Consistency: Keep the information in sync, achieving consistency.Collaboration: Easy to collaborate with others.So, "(only when they are great) they CAN give you the answer."Īvi also explains why we should consider the separation of content and presentation. What systems do we have, and how do they relate to each other?Īnd, he suggests that this question can be answered through "software architecture diagrams." Then, Avi mentions many would connect software architecture diagrams to a confused mess of lines and boxes, something like this. He says the fundamental question about software architecture is: Text-based C4 model diagramming tool, C4-PlantUMLĭata/text based software architecture diagrammingĪvi, our presenter, has a lot of experience in writing docs with internal software architecture.Experiences with software architecture diagramming.Data/text based software architecture diagramming.This is what I'd like to explain in this post: I'm going to share Avi Flax's Set your data free with model-based architecture diagramming in this blog post because I think his session can help us make the most out of software architecture diagrams. Even after you find a tool and start working on it, you would stop and seek advice if you're on the right track. You might not know which tool to choose or where to start. On the other hand, if you're not comfortable with drawing software architecture diagrams, it would take a lot of time and effort to accomplish the same goal. That's why we often rely on software architecture diagrams when we collaborate with colleagues or have a meeting with partners. You probably would agree that software architecture diagrams are an easier and quicker way to understand the big picture of software architecture as opposed to plain text. While I was there in person to attend Write the Docs Prague back in 2018, it went online in 2020 so I had to participate remotely. In this post, I'd like to introduce one of the sessions from Write the Docs Portland 2020 online.īefore directly jumping in to the main story, why don't you think back to your own experiences with software architecture diagrams. Among those changes, one of the more noticeable ones was that most conferences have shifted to being held online. COVID-19 has brought a lot of changes to our lifestyles. My name is Jeongil Kang, and I'm a technical writer at LINE. How are you all doing? I can't help but ask about your well-being first amid the ongoing COVID-19 pandemic.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |