You’re a system architect who needs to manage documentation. What’s the best cloud-based tool for the job?

This is a personal or team preference, the important part is that the documentation exists, is useful/insightful and extendable. I personally like to keep everything in the codebase with markdown files, but other systems such as notion are also ok as long as it has a history of the changes made.

I see that other people on this thread have recommended Confluence, and this tool certainly gives capabilities for collaborative editing. My main reservation about Confluence is it's lack of connectivity to true modeling capabilities, for example for UML diagrams. It's true that you can create pseudo-UML diagrams with Gliffy, and there is also a PlantUML plugin so that you can do UML texts and render as a diagram. However each diagram is stand-alone and there is no real model. This is a far cry from a coherent UML model where all the items (classes, actors, components, etc.) are connected (applications such as Sparx Enterprise Architect and the IBM Rational suite come to mind). Maybe there are collaborative add-ins for Confluence for this.

Uma excelente ferramenta para documenta??o é o Atlassian Confluence, nela é possivel ter rastreabilidade, versionamento, seguran?a e escalabilidade dos documentos. Além disso é possivel a defini??o de modelos que facilitam as novas cria??es. é uma excelente base de conhecimento para a organiza??o.

Cloud-based tools should behave like the Platform. They should be able to build more complex tools upon. They should charge less when used more. A tool simply hosted on a cloud provider is not a cloud-based tools unless it also projects and demonstrates cloud-like properties.

For me, the best tool is one that the team prefers or is actually going to use. Documentation is critical for the success of any IT organization, so whatever tool fits the needs and the team will actually use is the best one

Advanced Search: The capability to rapidly and efficiently search for documents using keywords, advanced filters, and metadata to promptly access the required information. Versioning: The capacity to monitor and manage different document versions, a critical aspect for traceability and change management. Automated Workflows: The ability to establish automated workflows for approving, validating, and electronically signing documents, thereby expediting processes. Integration: The option to integrate the documentation management tool with other applications and services you utilize, including email systems, collaboration tools, cloud services, and more.

Confluence, es una especie de Wiki, pero integrado con todo el ecosistema de attlasian, lo usamos aca en mi trabajo y maneja espacios de documentacion colaborativa, segmentado por grupo de usuarios que tienen acceso a ciertas partes del arbol de documentaicon

Rich Text and Diagramming Tools: The ability to create detailed diagrams and rich text formatting is essential for clear and effective documentation. Integration with Other Systems: Look for tools that can integrate with your current architecture, development, and deployment tools. Template Support: Availability of templates to quickly create standard documents such as technical specifications, architecture diagrams, and reports. Commenting and Review Features: Facilities for reviewers to leave comments and feedback directly on the documents. Access Management: Tools should allow you to finely control who can view, edit, or share your documentation.

Living documentation is the result of the capability of real-time collaboration, advanced full-text search with generative AI bots for effectively reaching valid content, plus possibility to automate processes would be a plus.

The most critical features of any documentation tools are the security features: how would it be possible to use a tool that can't be trusted? Encryption of data, backups, identity management are the first things to consider. Free/Libre Open Source Software like Dokuwiki, Mediawiki and NextCloud all deliver these features so the choice is actually pretty easy: the cloud-based documentation can never be a good idea.

Here are additional benefits and considerations to keep in mind when selecting the right tool: Microsoft 365 (formerly Office 365): It offers a comprehensive suite of cloud-based productivity tools, including Word, Excel, PowerPoint, and SharePoint. It is widely adopted by businesses and ensures excellent compatibility with Microsoft file formats. Dropbox: Known for its user-friendly interface and file synchronization across different devices, Dropbox also supports file sharing and real-time collaboration. Box: Tailored as a cloud content management solution for enterprises. OneDrive for Business: As part of the Microsoft 365 ecosystem. Also: Zoho Docs, Adobe Document Cloud, Trello, Evernote, Slack and GitHub.

We have used several cloud-based system documentation management tools over the past few years. For one client in particular, we were very pleased with Confluence, a documentation management tool developed by Atlassian. We used it for document creation, collaboration, and organization. It is cloud-based and allowed us to create wiki pages, documents and diagrams. In our intranet we used Microsoft Teams and SharePoint for document creation, management and collaboration. SharePoint in particular for wiki creation and documentation management. Sporadic uses have been made of Bitbucket, Box, Docuwiki and Google Docs. We have paid particular attention to safety management which must be inherent in the products.

There are several solutions out there. Google suit had a good start of cloud-based documentation tools (sheets, docs, etc). They were kind of limited version of Microsoft then-offline products, but more powerful as an online tool. Later Microsoft came along with their extensive 365 online packages from traditional Word/Powerpoint to Forms, Planner, etc. Both big tech companies have their fans, however I think a wiki style documentation platform provides more flexibility and ease to work with as a team and as an organization. For example, Atlassian's Confluence offers a strong search engine through your entire organization documentation. It offers proper user access management and ready to use templates for different kind of documentations.

Several cloud-based tools streamline documentation, enhancing collaboration and accessibility. Options include * Atlassian's Confluence, a widely-used tool with architecture templates * Lucidchart, a real-time collaboration-enabled diagramming tool * Gliffy, a diagramming tool integrating with Confluence and Jira * Microsoft Azure Architecture Center for Azure resources; * Google Cloud Platform Architecture Diagrams for GCP documentation * AWS Architecture Center for AWS systems * Miro, a real-time collaboration whiteboard * PlantUML, an open-source tool for diagrams from text. Consider collaboration features, ease of use, integration, and alignment with documentation needs when selecting a tool.

I’ve used Google Workspaces with 3rd party apps such as Confluence with much frustration. Documentation becomes obsolete after a few years and hard to maintain. Artifacts get spread across two locations making it difficult to manage and find information. On the other hand, Microsoft 365 has an integrated system — if you use Teams or Sharepoint — that surpasses all other documentation systems out there. Plus with the introduction of Copilot, you can find insights on your project to produce even better documents. Google Bard will help in this area but you need to work inside Workspaces and stop using 3rd party apps. This is the limiting factor.

Atlassian Confluence is a great choice, however, documentation becomes outdated after some time. Hence I always prefer extensive comments in source code files and elaborative readme files.

For any documentation to stay relevant without going stale is to make sure that the system architecture documentation is closely tied to code repositories, so GitHub Wiki comes handy Also, SwaggerHub is specifically designed for API documentation for system architecture involving APIs. It supports the OpenAPI Specification as well. Other Important tool is Confluence - A widely used collaboration tool that allows teams to create, share, and collaborate on documents. It offers a user-friendly interface and supports the creation of rich content, making it suitable for system architecture documentation.

I've seen a number of comments about documenting code internally via comments. I completely understand the importance of commenting code. What's just as important is to document code standards that include naming and style conventions. If these are in place, even without comments, code will be more easily readable. Any developer on the team familiar with the standards should be able to understand the code as written. Any comments added will of course still be helpful and valuable to anyone who reads or edits the code later. Unless coding standards and conventions are followed & enforced for every member of the team, code will generally be difficult to follow regardless of the number of comments. Tools like PMD can help enforce standards.

Depending on these factors, you may want to consider options like Microsoft 365 (if you work in a Microsoft environment), Google Workspace, Dropbox Business, Box, or specific content management tools like Atlassian's Confluence or Notion. Each of these tools has its own advantages and disadvantages, and the best choice will depend on your specific needs as a systems architect. It is recommended to test multiple options to determine which one best fits your workflow.

The same tool that the rest of the company uses. This is more important than the features of the tool since you need this close integration and even more - that the employees will use it.