Docs Italia, the start of a revolution. Making public projects more effective and transparent
Open government: the new version of Docs Italia, the result of a year’s collaboration with administrators and stakeholders working to change the language of Public Administration projects
by Lorenzo Fabbri and Giovanni Bajo
Questo articolo è disponibile anche in italiano
“Don’t tell me I can’t do it; don’t tell me it can’t be done!” said Howard Hughes played by Leonardo DiCaprio in The Aviator (2004). “If you can dream it, you can do it” was Walt Disney’s motto. These are the words that ran through our heads when we decided to apply tools developed in an open source environment to the world of Public Administration documents. We began to experiment and, after a year of work and analysis, today we are launching a new version of Docs Italia. Our goal is to change the language through which guidelines and documentation regarding Public Administration projects are built.
Our passion for the open source world isn’t the only thing that drives our experiment. Mostly, we’re driven by the concrete need to make public projects more effective. We need instruments that are capable of helping hundreds of thousands of people – both technicians and administrative staff – to work together and more effectively on the digital transformation of the country.
The Internet, and open source culture in particular, is revolutionizing the organization of knowledge on the basis of certain directives: participation and constant interaction, the extremely rapid flow of information and the existence of online work and collaboration environments that are open to contributions from everyone. Docs Italia intends to apply these principles to the daily routine of the Public Administration by offering new tools and providing a dedicated team of tech that follow the Public Administration’s guidelines for content design and can draw on the similar experiences of other countries to simplify language and encourage participation.
WHICH DOCUMENTS?
In the last twelve months we’ve followed this logic: publish every type of document relating to some of the country’s most important public projects in one place, so that the people who are working on them, manage them and develop them can take advantage of a modern environment for learning and collaboration.
So far on Docs Italia we have published documents related to the national registry (the ANPR project), citizen digital identity (the SPID project), the online payment system (pagoPA), the 18app project, the guidelines for data management and for the design of public services. We have, at times, also involved the Ministries and software houses participating in the publication process (from Sogei to SIA-payment systems, from Agid to the State Mint and Polygraphic Institute and many others).
At the same time, we have also started publishing other types of documents, for example, those of a more administrative or analytical kind. We like the idea that the people working on a project will be able to find everything they need (and not only technical documents) in a modern format, open to comments, easy to consult. This is why, in May last year, the Plan for Digital Transformation, signed by the Prime Minister, was published on Docs Italia and in January of the present year, the Parliamentary Inquiry Committees on the digitization of Public Administration, chaired by Mr. Paolo Coppola, published its final report on the platform as well. The Digital Administration Code (CAD), the law regulating Italian digitization, can also be found on Docs Italia; the aim is keeping track of the regulation changes over time. It is interesting to note that the publication of the CAD in this form has, in turn, spawned new experiments in analysis and visualization from the open source community. More recently, we have started using Docs Italia to manage public consultation, in the spirit of an open government philosophy: the first example of this is a roundtable discussion related to the Public Administration’s cloud services.
THE FEATURES OF DOCS ITALIA
Thanks to the Three-year Plan for Information Technology in the Public Administration and the Code for Digital Administration, Public Administrations are invited to work on public projects in a different way: more open, transparent and collaborative. In doing so, they will have new tools to work with, such as Developers Italia, the community of public service developers, which provides support for the publication and reuse of source code, or Forum Italia, the space to discuss, ask questions and seek help in solving problems related to the implementation and management of Public Administration projects and technologies.
Docs Italia is the third of these tools and serves to build a base of common knowledge on how to manage the projects of the Public Administration; it is a service devised by the Public Administration’s Digital Transformation Team in collaboration with AgID. It is managed by an interdisciplinary team of developers, designers and tech writers who are experts in documenting a project, whether it involves guides, guidelines, FAQs or technical documentation.
Docs Italia is inspired by five principles that we deem necessary for building a common language of public project management. First, in today’s world, documents are no longer the product of a single individual or office but the results of collaboration between different people and different professional, technical, economic and administrative profiles. Second, Public Administrations following the open government philosophy of tend to encourage contributions from the community and external points of view. Third, Public Administrations need shared methods and guidelines for managing the information related to a project, from the guidelines themselves to technical documentation. Fourth, i documents are not static objects carved in stone or printed on paper. They evolve over time;being able to keep track of this evolution offers several advantages. Fifth,documents are being used more and more often on the Internet, especially through smartphones: the simplicity of reading makes a difference.
TO KNOW MORE
Public Administrations and software houses that want more information or want to try publishing a document, with our support, can write to us or discuss it on the forum. The second part of this post is dedicated to those who want a deeper understanding of the project. It further illustrates some of Docs Italia’s many uses and features and the possible developments we’ve been working on.
In Further Depth: features and possible developments of Docs Italia Technologies
Technology
Docs Italia is an MVP (minimum viable product) created by a small development team and based on the open source project Read the Docs and on the Sphinx theme. We also use a lot of Pandoc for document conversion. Starting from here, we are working to enhance all aspects of the platform on the basis of the needs that emerged during this first year of experimentation: a document converter, publication flow and the search and navigation functions.
Collaborative Writing Features
There is a tendency that characterizes the way in which people today produce documents of all kinds. From academic papers to school exercises, from business plans to meeting summary reports: writing these documents is increasingly taking place in a collaborative way: “by different hands,” so to speak. People writing a text compare information, exchange opinions and work together “in real time” until the text is ready. After its publication, they continue to improve it. The product is often also enriched by the contributions and comments of those who may not necessarily have worked on drafting the document, but intervened in a second phase, bringing into it an external point of view that is often crucial. Docs Italia follows this trend, allowing for the production and collaborative evolution of documents.
Participation and public consultation
Docs Italia encourages the production of comments, which, in turn, favors collaboration and contribution of external points of view; also, it fosters he public consultation process of an administration document envisioned by article 18 of the Digital Administration Code.
Comments and proposed edits can be sent in different ways (including through GitHub) but our aim is to integrate Docs Italia with Forum Italia to experiment a public consultation model by which the comments made on the document are available on the Forum and can feed into the discussion. Here it is an example of a discussion relating to cloud services managed in Docs Italia and Forum Italia.
A common language for projects
Docs Italia is becoming the place where Public Administration and its service providers – hundreds of projects and hundreds of thousands of people – can have access to an overview of current public projects. Having documents in a single environment and in one format helps those who work on them by fostering a method that combines technical, administrative, service design and economic aspects. For similar reasons, being able to compare and connect different public projects to one another, promotes the exchange of knowledge and offers opportunities for learning and mutual assistance. Think, for example, how advantageous it would be for the twenty thousand Italian Administrations to have in the same place, in the same format and with all the needed hypertextual references, all the instructions to install and use the payment system (PagoPA) or to integrate the authentication system (Spid). At the same time, we are working to enrich the Public Administration’s content design guidelines with a section dedicated to document management and the writing of technical texts.
Documents change over time
In the world of technical documentation there’s a practice of managing digital documents by applying an identifying number to each version. It is the digital evolution of the publishing concept of subsequent editions and, by all accounts, it is a very useful tool for every type of digital document. For example, a document like the Design Guidelines was published last year in version 2017.1 and then, at the beginning of this year, it was republished in version 2018.1. It is both interesting and easy to verify the changes from one version to the other. By using the version control system based on Git, Docs Italia allows the reader to track easily the document variations by keeping all its versions to allow comparison.
Easy reading, even on a smartphone
Last but not least, the final principle. We are increasingly using smartphones to view content on the Internet; therefore, it is important that even technical documentation, guidelines and the descriptions of a project are easily viewable on a small screen. The documents published on Doc Italia have this feature, which makes them easy to consult and more like a website than a PDF. This solution allows to overcome some of the limitations of a PDF, a type of document made for the press. The documents in Docs Italia have an accessible practical index; they are very readable on a smartphone and, if you come across an interesting passage, you can send a link to that specific part to a colleague, something you cannot do with a PDF. Finally, Google can index content more precisely and accurately, making the documents easier to find.
Next steps
We are developing Docs Italia as if it were a start-up, working on technology and service simultaneously. Here are some of our ideas.
- We want to increase the quantity and variety of the Public Administration documents on Docs Italia so that we may continue to experiment. Recently, we have started the publication of some documents from the Department of Public Administration.
- We want to support other Administrations that, in the coming weeks, will start managing their project documents through Docs Italia. We are dedicating a team of tech writers to support them in the publication process.
- We have published a beta version of the registration and publication workflow. Each new project that appears on Docs Italia gives us new ideas on how to improve the process and simplify it, so that everyone can become progressively more autonomous (or at least, semi-autonomous), when it comes to publication.
- We want to improve the integration between Docs Italia and Forum Italia, making the comment system more effective and building better correlations and courses of action for users.
- We are building a search engine for the documents; this service will become more and more important with the increase of managed projects (the internal search engine for a document is already available).
- We have published on Docs Italia a beta version of the style guide for the drafting of project documents, and we are working on a style guide – of a more general nature – for writing public texts on the web. As mentioned above, we will produce guidelines for the writing and management of project documents and technical texts as an evolution of the current content design guidelines for Public Administration web sites.
If you want to follow the evolution of the project, check out this link to see our Trello board that is built according to the user stories method.
Join Us| Follow us on Twitter and LinkedIn | Visit our Website | GitHub
