multi-topic-level version 1.0 Template Git Repository

This is a fully-customizable Git repository that can be quickly and easily cloned to begin new documentation projects, or migrate old documentation projects into the repository structure that Content Services is converging on as part of our FY17 goals.

Terminology

This template repository uses the terms below as defined:

title

A title is a deliverable, i.e. a piece of content that is publishable using our toolchain. The toolchain refers to an AsciiDoc or DocBook deliverable publishable with it as a title, and this repo template adopts the same terminology.

distro

A distro is shorthand for "distribution" and is similar to the concept of a Linux distribution such as Fedora. A Linux distro is a customized "spin" of the Linux kernel along with a customized userland . A distro for our purposes is a certain set of docs that is released under a certain downstream product or upstream project name.

topic

A topic is considered to be an atomic chunk of content contained within a single file. It may or may not be self-contained. In the future, it is likely to adhere to a content model such as concept, task or reference.

Properties of *multi-topic-level *

This template repository structure has the following properties:

This repository structure has the following properties:

• It is verified to work with the Tooling team’s Docs2Drupal (and soon Docs 2.0) publication systems.

• It is based on the "library," or "multi-title" repo model. This repository structure can work with any number of titles, from one to whatever.

• The repository structure serves to make it clear which content—usually toics—is/are shared between different distributions ("distros") of a title, shared between more that one title, or potentially local to a single distro of a title.

• The need to use file-naming conventions to signify levels of sharing (a.k.a. "Hungarian notation") is reduced due to the directory structure making it more explicit.

• It can be mirrored between Github and Gitlab by the Tooling team.

• Content from other repositories can be pulled into this one using the Git subtree (or Git submodels if absolutely necessary).

• This repository structure has been structured so that it works with discrete chunks of content included from the topics and topics/shared subdirectories of each title. That is, it is based on, and will work best with, a topic-oriented content development model.

In addition, this repository structure has been designed to work with the following content development models:

• All content development is performed in the Github repository, for any number of titles and distros, provided that release versions are more-or-less in sync between those distros. The Github repository is mirrored to Gitlab solely in order to publish using the Docs2Drupal/Docs 2.0 toolchain (i.e. Pantheon).

• Upstream content development (by engineering, community members, etc.), for any number of titles and distros, happens in Github. Downstream development (by CCS, engineering), for any number of titles and distros, happens in Gitlab.

• All content development for any number of titles and distros happens in Gitlab.

• This repository structure is extremely flexible and should be able to account for any other development models. Contact Silas if you have any questions about whether this repository structure can work for your project.

Repository Structure Overview

├── README.adoc
├── docs
│   ├── my-title-a
│   │   ├── enterprise
│   │   │   ├── master-docinfo.xml
│   │   │   ├── master.adoc
│   │   │   └── topics -> ../topics
│   │   ├── topics
│   │   │   ├── shared -> ../../shared
│   │   │   ├── topic-1.adoc
│   │   │   ├── topic-2.adoc
│   │   │   ├── topic-4.adoc
│   │   │   └── topic-5.adoc
│   │   └── upstream-1
│   │       ├── master-docinfo.xml
│   │       ├── master.adoc
│   │       └── topics -> ../topics
│   ├── my-title-b
│   │   ├── enterprise
│   │   │   ├── master-docinfo.xml
│   │   │   ├── master.adoc
│   │   │   └── topics -> ../topics
│   │   ├── topics
│   │   │   ├── shared -> ../../shared
│   │   │   ├── topic-1.adoc
│   │   │   ├── topic-2.adoc
│   │   │   ├── topic-4.adoc
│   │   │   └── topic-5.adoc
│   │   └── upstream-1
│   │       ├── master-docinfo.xml
│   │       ├── master.adoc
│   │       └── topics -> ../topics
│   └── shared
│       ├── attributes.adoc
│       ├── images
│       ├── templates
│       │   └── revision-info.adoc
│       ├── topic-shared-1.adoc
│       └── topic-shared-2.adoc
└── resources
    ├── asciidoc-writing-guide.adoc
    └── scripts
        └── buildGuides.sh

How to Use This Repository Template

Getting the Repository Template

The easiest way to use this repository template is to grab the latest tarball release from https://github.com/silasrh/multi-topic-level-repo-template/releases and extract its contents. The tarball is identical to a fresh clone of the Git repository except that it does not contain the .git directory.

Note: the latest release as on 2 Jan. 2017 is 0.9, which is considered to be "production ready" for documentation projects.

Alternatively you can:

1. Clone this repository:

   $ git clone https://github.com/silasrh/multi-topic-level-repo-template.git

2. Delete the .git directory.

Important: in most circumstances, deleting a .git directory is a really bad idea and not what you want to do. However, because this Git template repository is only intended to provide a certain directory structure, and its history is completely useless to projects which use it, it is permissible to delete the .git directory in this case, as an exception to the general rule. If you don’t delete it, the history of the template repository will become part of your project’s history, which probably isn’t want you want.

$ cd multi-topic-level-repo-template
$ rm .git -fr

Configuring the Repository Template

1. Modify the global attributes in docs/shared/attributes.adoc for your project.

2. Make modifications to the first title:

3. Copy the entire docs/my-title-a directory and its contents to docs/<your_actual_first_title_name>.

4. Rename the enterprise and upstream-1 directories to match the names of your distros.

5. Define the my-title-a and product-build attributes in master.adoc. Ensure the first title builds after the modifications and then repeat these steps for each additional title.

6. Remove any directories for distros that you have not customized for your project:

   • Under docs/, delete the directories for any titles that you do not require, such as my-title-b if you do not have a second title. This helps to avoid confusion. Note that these template directories can always be copied from this repository in the future, if needed.

   • Under docs/<titles>/, delete the directories for any distros that you do not require, such as upstream-1 if you do not have an upstream. This helps to avoid confusion. Note that these template directories can always be copied from this repository in the future, if needed.

7. If you are migrating existing content to this repository template, it is recommended to put all content into the topics directories for the appropriate titles, even if the content is not shared between distros. (There are more reasons for putting content that isn’t shared between distros of a title or multiple titles into the <title>/topics directory, at least at first, but they are beyond the scope of this README. For a discussion of the reasoning, which touches on content development workflow, contact Silas.)

8. Remove this README.adoc file, or overwrite it with the details for your project! Do not leave this README as-is for your project!

9. TBD: Full instructions should be provided for hooking this repository up to Pantheon. In short:

   • You must set the Content Directory for each book to <docs>/<title> *

multi-topic-level Revision History

1.0

• rename My_Title_A, My_Title_B and Upstream_1 directories to my-title-a, my-title-b and upstream-1 naming patterns to make navigating the Git repo as fast as possible.

• docs/shared/templates/document-attributes.adoc moved to docs/shared/attributes.adoc.

• all includes of document-attributes.adoc changed to correct for new attributes.adoc location.

• scripts/buildGuides.sh moved to resources/scripts/buildGuides.sh.

• latest version of the EAP team’s asciidoc-writing-guide.adoc added to the resources directory for referential convenience.

• RepoTemplateVersion and RepoTemplateCodeName attributes defined in docs/shared/attributes.adoc.

• remove topic-6 and topic-7 because they are unnecessary for illustrative purposes.

Pre-1.0

• contains typo in repository structure diagram: "images — This folder contains all imagess"

• buildGuides.sh (98 lines, 86 sloc) does not work correctly because it had not been updated from the script developed by EAP