Document administration

This section describes all the tasks carried out by document administrators at different moments of the authoring workflow.

The first and most important task is the creation and configuration of a GitHub repository to work on a document. Documents follow one of two possible workflows:

  1. They are directly created as Asciidoc documents. In this case the creation of the repository is truly the first action to undertake.

  2. The document is written in some other (collaborative) platform, and then converted to Asciidoc. Here we can create the repository at any time before the conversion.

The conversion to Asciidoc is a one time, single direction action.

Once a document has been converted and stored in its Git repository, trying to edit it with different procedures than described in Section Document authoring of this guide is strongly discouraged.

Create the repository for a new document

Every document requires the creation of a new repository in Decidim’s space at GitHub.

Decidim’s organization page on GitHub

The document administrator needs to be a member of the Decidim organization at GitHub to be able to create new repositories for Decidim. Ask to an owner of the Decidim organization if you are not already a member.

The steps to get the new repository are described in the following sections.

(Step 1) Import the repository template for new documents

Importing a repository is a different concept from forking or creating an empty one.

Go to the + ▾ drop down menu on GitHub’s top bar and select the Import repository option, as shown in the following figure:

Import repository option
Figure 1. GitHub import option

Decidim has a repository with a template for new documents called docs-new-document-template. As shown in Figure 2 below:

  1. Input https://github.com/decidim/docs-new-document-template.git as the repository to clone (i.e. import from).

  2. Select decidim organization as the owner of the repository, if you have other options. If this option does not appear, you probably do not have the needed permissions (see the beginning of section Create the repository for a new document).

  3. Choose a name for your new repository that begins with docs-, a convention we use to easily find documentation repositories.

  4. Press the Begin import button.

The import can take some seconds or minutes.

Import repository
Figure 2. GitHub import form

In contrast with a GitHub fork, a repository import does not keep any link to the original repository (in this case, the template).

Our new repository template defines the basic file structure to facilitate:

If you want to understand what is in the template, its contents are described in section Anatomy of a document repository.

(Step 2) Add collaborators to the repository

Once the repository is created, you can visit its main page in GitHub. If you called it, for example, docs-my-great-content, the URL should be https://github.com/decidim/docs-my-great-content.

By default only you (the creator and administrator) can write to the recently created repository. To enable collective writing you must add collaborators going to Settings  Collaborators & teams.

Add the team docs and any other individual or team collaborator that needs access to the repository. Give them "Write" permission.

github collaborators
Figure 3. GitHub collaborators form

(Step 3) Protect the master branch and add explicit permissions to it

Go to Settings  Branches. Under "Branch protection rules", choose branch master.

Select options "Protect this branch" and "Restrict who can push to this branch", and deselect all other options. In section "People and teams with push access" add all the people and teams that you added in (Step 2) Add collaborators to the repository. Push Save changes.

github branch protection
Figure 4. GitHub branch protection options

Protection of branch master gives us an extra guarantee that nobody will overwrite this branch by mistake. All changes will be incremental and it will be possible to undo them if necessary.

(Step 4) Add a short description to the repository

At the top of the Code panel you will see the following message: "No description, website, or topics provided." Press the Edit button on the right to change the description. Try to use one single sentence, at most two.

github edit description and topics
Figure 5. GitHub’s Edit description button and topics option

(Step 5) Add topics (labels) to the repository

As shown in Figure 5, there is also an "Add topics" option. Press it. Add at least the topics decidim and decidim-docs.

(Step 6) Configure other repository options

Go to Settings  Options and disable "Wikis" and "Projects". Leave the other options in its default configuration.

github repo options
Figure 6. GitHub’s repository options

Additional steps

Once created and configured the public repository, the next steps the administrator can take (or task a capable writer with) are:

  1. Fill up the metadata for the document.

  2. Create an Asciidoc file for every web page we want to show in https://docs.decidim.org (we usually show every major section or chapter of a document as a separate web page).

  3. Convert the document to Asciidoc, if we already have a preliminary version in Google Drive or written in any other format.

  4. Set up the document for publication at docs.decidim.org.

If you have just imported your first document template, you may want to read section Anatomy of a document repository, to understand how files are organized in the repository.

Convert a document to Asciidoc

We use a command-line conversion tool called Pandoc. See how to install it at Install Pandoc.

Pandoc can convert from Libre Office, Microsoft Office, HTML, and many other formats to Asciidoc.

Imagine you have a Microsoft Word (sic) document called MyAwesomeDoc.docx. You can run (copy it as a single line command):

pandoc --to=asciidoc --wrap=none --atx-headers  --extract-media=images --output=my-awesome-document.adoc MyAwesomeDoc.docx

A beautiful Asciidoc file called my-awesome-document.adoc will be created with the text of your document. If the original document contains any image, an images directory will appear containing a file for each image. Images will be correctly referenced in the Asciidoc file.

The above command is independent of input format, you only need to change your input and output file names (e.g. replace MyAwesomeDoc.docx to MyAwesomeDoc.html). Option --wrap=none means that lines will not be cut at some fixed width (by default 72 characters) at it is typically done in source code.

Option --atx-headers means headers will be set as

= Introduction

and not

Introduction
~~~~~~~~~~~~

Some recommendations when you convert with Pandoc:

  1. Unfortunately, conversion from Microsoft Word or HTML seems to work better than from OpenDocument (.odt). If your original document is in Google Drive, you can choose to store a local copy in either Word (File  Download as  Microsoft Word (.docx)) or HTML (File  Download as  Web Page (.html  zipped)).

  2. Which conversion path is best depends on the document. For complex documents it may be worthwhile to try some possibilities before choosing.

  3. Do not convert full documents, first copy each section in a different file and then convert section by section.

  4. Do not copy the front page or the table of contents. Those need to be re-created from Asciidoc.

  5. Remove section numbering before converting. We want Asciidoc to number sections (and figures, tables, etc.) automatically. This can be done in a single action if your original document uses header styles consistently. It can also be done after the conversions, but it is usually more work.

After the conversion, you will need to adjust some things manually:

  1. When you move your files to the repository, images will be placed under the default image directory, assets/images, and all references to images in your .adoc files will need to be adapted accordingly (in essence, its path removed).

  2. Header identifiers (or any other element identifier) could have been created, and could be useful. If you want to rename them, do it consistently. If some of them are spurious, remove them.

  3. Cross references and footnotes may need manual intervention also.

Pandoc has many other options described in the Pandoc User’s Guide.

Publish at docs.decidim.org

The site https://docs.decidim.org is generated from a number of repositories with a static site generator called Antora.

There are three kinds of repositories involved:

  1. A number of document repositories with the contents we want to show in the documentation site. They are based on the document template.

  2. A site repository, https://github.com/decidim/docs.decidim.org, that contains:

    • An Antora configuration file site.yml that acts as a playbook for the site (all document repositories URLs to pull from are listed here, along with some global configuration options).

    • A landing-page directory that contains the landing page for the whole site (and potentially other static global pages). The landing page is also written in Asciidoc, following the same conventions as in document repositories.

  3. An Antora UI repository: https://github.com/decidim/docs.decidim.org-antora-ui. It contains all the presentation stuff (HTML templates, CSS files, Etc.). It is also referenced by the playbook.

To publish a new document in the site you need to follow the steps in this section.

TODO: how to update a document (with a preview).

(Step 1) Set up the Antora document configuration file

If you have correctly applied the document template, your document repository contains, for every language {LANG}, a file called {LANG}/antora.yml. It is a YAML file following the syntax property: value. You have to fill up the different declared properties following the instructions given in the same file.

Do not confuse this file with the site’s playbook, called site.yml and stored at https://github.com/decidim/docs.decidim.org.

(Step 2) Check that single-page.adoc and nav.adoc are OK

For every language {LANG}, there are files called:

  • {LANG}/modules/ROOT/pages/single-page.adoc

  • {LANG}/modules/ROOT/nav.adoc

If you and your collaborators have followed the instructions in section Create new documentation page, then all should be ok, but this it is the moment to double-check.

(Step 3) Add the document to the site repository

Here you need to change the site repository, https://github.com/decidim/docs.decidim.org.

This time we will follow a proper Git workflow:

  1. Make your own GitHub fork of the site repository. Work with your copy in the following numbered items.

  2. Edit file site.yml to add the new document under the content section (repeatedly for every language). The syntax for the content section is described in the Antora Manual.

  3. Edit files landing-page/{LANG}/modules/ROOT/nav.adoc and add a cross-reference (xref) to the first page of the new document (and other pages if needed).

  4. Edit files landing-page/{LANG}/modules/ROOT/pages/index.adoc and add a cross-reference (xref) to the first page of the new document.

  5. Commit your changes and make a pull request (PR). If everything goes well you will an automatic comment to the PR with an URL for a preview. Use the preview to check that the site looks fine.

  6. Either accept the PR, if you have permissions to do so, or wait.

TODO: Manually deploy from the Netlify web interface is needed at the moment.

Generate a PDF file

TODO.

Add a new language to a document

Here we have two different cases:

  1. Add a language already present in the document template (Catalan, English, Spanish).

  2. Add a new language not present in the template.

For the first case you can basically follow the same steps needed for creating a new page, but this time you may need to add more than one file.

In the second case, you can simply replicate the necessary directory structure for the new language, but in case the new language is going to be used in many future documents, you better update the template.