In many software development projects, they find that these documents are a sign of failure and frustration. It took a long time to write, was very difficult to understand and by the time the development team reviewed the document, the content was often outdated.
One of the reasons for the success and popularity of the active method is the way shareholders and development teams work together. Rather than writing lengthy paperwork (in most cases without input from the development team) shareholders continue to collaborate on ongoing planning, customer story writing, stories, sprint appointments, and other agile and scrum tasks.
However, some have extended this principle so far, with some arguing that the Agile team does not need or need to create the document.
This lawsuit has its own reasons. This is very often the case when shareholders and product owners do not trust the development team, so they ask for detailed documentation instead of trust. Now there are also technological development platform and tools that integrate into the workflow, but during the first decade of Agile’s growth, the process of creating, maintaining, searching and using knowledge bases was no longer as convenient.
Why create and maintain documents
Today, companies are developing more software than ever before and the DevOps team releases changes from time to time. Therefore, technical management and technical documentation management is very important.
People expect the DevOps team to create APIs, integrate cloud-native applications and other systems, and improve long-term functionality. When any event, security issue or other error occurs, shareholders believe that the Agile team will easily resolve the issue and release the changes.
However, no one wants a situation where in the next ten years the development team will be struggling with legacy systems and technical debts. It is unrealistic for new developers to join a software development project and learn how a system works without documentation.
In addition, data scientists often use the underlying data generated by microservices and applications to create analytics, data visualization, and machine learning models. Data scientists need document definitions and business rules documentation to understand how to use data properly and how applications generate and update data.
Finally, most companies are in regulated industries that require documentation of user interfaces, workflows, algorithms, business logic, data catalogs, and system changes. Documentation is mandatory for these organizations.
Use main utility targets and cases
Software, data and architecture documents include a number of user and usage cases, including:
- Development teams that work primarily on microservices and applications, but also look at the different aspects of systems created by other teams working on dependencies and releases.
- IT operations, business operations, information security, IT service management professionals and site loyalty engineers who need to understand architecture, workflow, business logic, data and error situations.
- Product owners, customer experience professionals, designers and marketers need to understand maps, web analytics and end-user usage policies.
- Data governance experts who need to check data for security, privacy and compliance.
- Data scientists, dataps engineers and data stewards want to validate data quality, build master data sources and influence application data resources in the following analytics and machine learning models.
- Developers, business analysts, test automation engineers, Devops engineers, etc. are all new to the company and need to maintain and improve the code developed by their predecessors.
Following naming conventions, creating a code that can be read and documenting code is useful for current and future Devops teams, not just to support many other features and cases.
Additionally, to support new DevOps team members who need comprehensive documentation on architecture and data, APIs, business logic and user interfaces before reading code-level documentation, there are no requirements included in the code documentation and user stories.
The best way is to identify the shareholders of the document and prioritize their core needs. Active teams should consider how to classify document requirements in the backlog and agree on the protocol. If the user expects documentation in the story, it is a good idea to define acceptance criteria. For example, when developers code an API, they create an API documentation.
It is also a good idea to set custom Zira issue types, Azure Devops work item types or other card types in the scrumbacklog to display the documentation.
Authentication of knowledge management and documentation tools
Since only the DevOps team can read code documents, IT leadership must define knowledge management tools, data structure and documentation standards that meet the needs of all stakeholders.
When I went through the CTO of a startup and the CIO of a large company, I had a solid idea of the tools and standards. Companies can use Microsoft 365 or Google Workspace to create and manage documents, presentations and spreadsheets, but these tools are not very suitable for active development and knowledge base platforms used by Devops teams.
Useful engineering papers are often a mixture of diagrams, tables and paragraphs. Simple office applications are not the best choice.
Also, there are many times when links between documents are more useful than documents. For example, a data scientist can start with a single diagram, click on a service to explore the API, and then link to a data dictionary to see how to use the data source properly.
I encourage IT and DevOps teams to search for a knowledge management tool that connects to the workflow, supports great data building, and creates documents that can be used by all stakeholders.
For example Atlasian confluenceKnowledge management tool that recently won the InfoWorld 2021 Technology of the Year award. More than 60,000 companies use Sangam’s Enterprise Wiki to share documents and knowledge, and collaborate using Sangam templates.
Development teams that use Zira software use Zira macros to create custom views of backlogs, such as Glyph, Miro, Balsamic, DrawYo and Lucidchart. You can use the tool to embed diagrams in your wiki pages.
Other well-known documentation and knowledge sharing tools at Devops include Microsoft Teams Wiki and File Sharing, Microsoft SharePoint, BMC’s Commount, Service Knowledge Management and Pro.
Other companies are interested in document collaborators and portals that focus on knowledge sharing, such as Bit, Igloo, Jeeve, Lumops and Simpler.
The development team should also consider tools that document specific skills. For example, DevOps uses Swagger for API documentation or Fix Insight’s Discovery and Dependency Mapping to capture hybrid cloud infrastructure configurations and implement cloud architecture tools. Can be used.
Companies that build data science, self-service data visualization, data governance, data apps, machine learning and other analytical capabilities should centralize their data catalogs.
Create document standards and workflows
Once you’ve identified your target audience, prioritizing your documentation backlog and selecting your tools, it’s time to create documentation criteria and templates. The DevOps team must remember the end user when creating documents. Without standards for document and information structure, it is less useful to focus on content.
If you apply an active approach to the creation and maintenance of documents, ask for end-user assistance in defining the criteria for acceptance of valuable documents requested by end users and by product owners. At the time of document delivery, you can estimate customer satisfaction and use that score as a guide to document standards. High scoring documents can then be used as templates for documentation.
Another criterion for defining who is creating, updating and maintaining documents. DevOps team, it is irresponsible to continue releases frequently, neglect old documents or abandon document debt. Defining document criteria and expectations as part of the release and change management process is the best approach.
As we have seen so far, companies that follow sustainable development, devops and data science need to formulate knowledge-sharing governance and action plans. Technology is changing fast and technicians want to take on new tasks. Developing a culture of document and knowledge sharing is essential for long-term success. email@example.com