Community Collaboration Guide

Customer Content Services (CCS) is a Red Hat team responsible for producing documentation for Red Hat customers. Because all Red Hat products have an upstream, or open source community version, it makes sense for CCS to use these upstream resources in developing guides for customers. Many programs use pieces of upstream content in the downstream documentation. This framework defines best practices for single-streaming your documentation.

In principle, single-streamed documentation will be worked on completely in the upstream and brought down to the Customer Portal wholesale. In some projects, this process eliminates the overhead of maintaining two separate repositories for documentation content. This framework guides you through the process necessary for deciding if a community is a viable single-stream partner, setting up your repositories, choosing the right tools, and more.

Communicate with members of this community by signing up for our mailing list. To sign up send an empty email to ccs-upstream-subscribe@redhat.com. If you later want to unsubscribe, send an empty email to ccs-upstream-unsubscribe@redhat.com.

To report issues or request enhancements to the Community Collaboration Guide use the GitHub issues tool.

This sample communication survey can be used to determine if single-streaming documentation is feasible on a specific project. Content Strategists and Documentation Program Managers will work together to gather data to evaluate community documentation for their products. Using the results of this survey your team will be able to make a proposal for or against single-streaming documentation.

The top possible score on this evaluation is 100 and the bottom score is 50.

Create a new repository in GitHub.

The batch commit synchronization method is a method of copying content from one repository to another by downloading the content in a source repository, copying the files to the target repository, and committing the changes in a single commit (a batch).

Copy the changes in one repository to another using the batch commit method.

The batch commit script, fetch-upstream.sh, is a simple bash script that pulls down the latest upstream content, copying the relevant upstream files into the upstream subdirectory. The script exploits a particular feature of GitHub, whereby GitHub provides a downloadable archive file containing the working tree for any branch in the repository. The archive file has a snapshot of the latest content in a particular branch and thus provides an ideal basis for synchronizing content downstream.

To see how this works, consider the following sample fetch-upstream.sh script developed for synchronizing the contents of the Apache Camel Component Reference:

Given the simplicity of the batch commit script, you might get the impression that it is not as powerful as other approaches. But if you compare it with a mechanism that provides similar functionality — for example, Git submodules — it measures up well. Comparison of batch commit and git submodule makes a point by point comparison of the batch commit process against the Git submodule process.

If you need to migrate content from an existing downstream repository to an upstream repository, it is important that you plan these efforts. Planning should be a collaborative process between a representative of the downstream documentation team and the upstream community, and might require the building of a new relationship.

Use the planning process to discover and decide upon important details about the migration. For example, who are the main contacts in the downstream documentation team and the upstream community, what will the new workflow be, and how will changes to existing titles and development of new titles be handled when the content has been fully migrated and the new workflow put in place?

Most importantly, the downstream documentation team and upstream community must reach a common understanding about the key goals of the migration and how both parties will interact when the migration is complete. This might require participation in community meetings and holding workshops with the downstream documentation team to take them through the new workflow and communication guidelines.

The following is a basic checklist of considerations to make before migrating content from an existing downstream repository to an upstream repository. In principle, the content should be laid out in accordance with one of the structures outlined in Project Structure.

The first steps towards documenting a project are often found in the README file of the repository. Eventually the project will grow to where there is a need for more documentation than you can fit in a single README, and that may appear in the form of a project wiki, a separate installation guide, possibly a developer guide, and one or more user guides. You may start out with all of the documentation in the same repository as the code, but as things grow more complex, you may want to consider having a separate repository for your documentation. This makes it easier for community members who may only want to contribute to the documentation, as they don’t have to worry about merge conflicts in the code. For more information about considerations when sharing a repository with engineering, see Considerations for sharing a repository with engineering.

As your project grows, you should consider the structure you want to use for your documentation directory. Directories should be structured in a logical and related fashion. Many projects have a documentation repo or directory for their project web page, and possibly a separate repo or directory for the project documentation. You may choose to have separate repositories for each “manual” or you may choose to have all the documents in your doc set share a repository. Contribution style and build requirements are two primary considerations when you decide how to proceed.

In a flat file structure, there are no sub-directories, just one directory with all the documentation files in a single directory. A flat file structure might be as simple as a single README file, or contain a complete guide. A flat file structure for an AsciiDoc guide might look something like this:

In a flat file system, every file must have a different name because there is only one list of files. A flat file structure may work with a very small number of files, but once a documentation project becomes more complex, it becomes more difficult to have all the files in the same directory. And that is when the documentation for a project may require a more complex structure.

If you do not share any content between books, you may choose a single book per directory structure. A structure with a single AsciiDoc guide per repository might look something like this:

If you have common files that you want to reuse between books, you may choose a more complex directory structure, where all the books live in the same repository and have access to common files.

Note that in the following multiple-book structure, each “book” directory has a symlink to a common directory for topic files. This allows you to use any individual topic in any book, saving time writing and updating topics that appear in more than one place. This structure also uses a common directory for images inside the topics directory, again allowing for the reuse of images such as button icons and product logos. And the attributes file is also common, allowing for the same replacement variables in all files and books.

A structure with multiple AsciiDoc guides per repository and a single topic directory might look something like this:

And a structure with multiple AsciiDoc guides per repository and multiple topic directories might look something like this:

If you are considering sharing a repository with engineering, that is, for the software code and documentation to reside in the same upstream repository, here are a few things you will want to keep in mind.

The size of the combined repository will be large, so if limited space is an issue, keep this factor in mind.

When working in the same repository as engineering, rebasing frequently is often a necessity because engineering is making changes too. Before making any changes to the documentation you’ll want to rebase your fork.

Although you’ll be sharing the upstream repository with engineering, you’ll also need a downstream docs repository. Since more than likely the upstream repository branching structure will not match exactly the downstream docs repository branching, you will need to sync up the content.

Also, investing the time to plan a branching strategy in advance will save plenty of headaches in the long run.

To easily sync up content, use the git export script.

In general, using attributes will facilitate ease of use between upstream docs and downstream docs. One of the most useful is for the product name itself: {ProductName}. Other useful attributes include those for any version numbers used in the docs or any other product names. For more general information about how to use attributes, see AsciiDoc attributes.

In particular, using a variable for the upstream directory in the downstream docs repository is helpful. For example, define the following variable in the downstream docs repository attributes file:

Then, in the downstream master.adoc files, use the variable in the include statements:

Rather than writing your documentation in a single lengthy file, a best practice is to break the content up into small chunks. There are several reasons why this is a good idea. Having some sort of structure for your content provides many benefits for both readers and writers of your documentation:

See the Modular Documentation Reference Guide prepared by Red Hat for guidance on authoring documentation using a modular structure.

In general, when writing content you want to use simple language and avoid jargon that people unfamiliar with your project might not understand. Writing short sentences and short paragraphs also makes your content easier to read and understand.

No matter what repo and directory structure you choose, directory and file names should be clear and consistent.

AsciiDoc attributes are variables you can use in common files to:

To use attributes:

Common AsciiDoc attributes include product name, abbreviated product name, and product version. For more information about attributes and ifdef statements, see Attributes and Conditional Preprocessor Directives in the Asciidoctor User Guide.

The example below creates attributes for the Community Documentation brand.

In addition to storing product names and versions, attributes can be used to store book-local and cross-book links for your guides. Doing this allows you to:

To store a relative link as an attribute, you must define it in the:

Attributes can also store external link URLs, allowing you to update them without breaking any links in your guide.

Use the variable in a link macro. The variable will automatically resolve to the URL stored in the attribute when you build your documents.

To force your links to open in a new window:

If your project is not already written in AsciiDoc and you want to migrate from Markdown or another markup language, there are a variety of conversion tools available.

When your source content is ready to be reviewed or published, you can render it into a display format that can be hosted on a website, included directly in a product, or otherwise accessed by your users. The recommended tool for rendering AsciiDoc into a display format is Asciidoctor. Asciidoctor is a fully open-source, Ruby-based implementation of AsciiDoc, and is also the tool that GitHub itself uses to render the content of files written in AsciiDoc.

See the project home page for instructions on how to install Asciidoctor on a variety of platforms:

The following is the basic syntax for rendering content into a display format:

This command creates a single HTML file of the same name and in the same directory as the specified master file. The master file does not need to be in the current working directory, and you can specify either a relative path or absolute path to it.

In addition to this basic syntax, Asciidoctor also provides a number of options that allow you to customize the location and format of the content that it renders.

The following example outlines how to specify a custom output directory:

The following example outlines how to render the content as an article instead of as a book:

For additional examples, including instructions on how to render content in formats other than HTML such as PDF, EPUB3, and LaTeX, see How do I render a document? on the AsciiDoctor project home page.

AsciiBinder is a Ruby-based command-line tool that is designed to streamline the documentation and publication process for teams that manage a large volume of content and re-publish that content regularly. AsciiBinder allows you to share content across multiple distributions by using a map of content that is common to all distributions and by breaking the metadata for each distribution out into a separate branch in Git.

Website: https://github.com/redhataccess/ascii_binder

GitBook is a documentation hosting system based on GitHub.

Website: https://www.gitbook.com

Hugo is a static site generator written in Go.

Website: https://gohugo.io/

reStructuredText (RST) is a popular lightweight documentation format used by many, particularly Python-based, projects and open source communities. RST is often used alongside the Sphinx documentation generator, which can be seen as an counterpart of the AsciiDoctor toolchain for AsciiDoc.

In addition to providing a system to structure and maintain documentation for multiple brands using a single repository, AsciiBinder also provides the ability to preview and package documentation as a set of HTML files that you can publish on a website.

Run the following command to build a preview of the documentation:

The output of this command is saved in the <docs_repo_dir>/_preview/<distro>/<branch_dir_name> directory.

Run the following command to package the documentation:

The output of this command is saved in the <docs_repo_dir>/_package/<distro>/<branch_dir_name> directory. Each sub-directory in the _package represents the website content for a single brand, and can be copied to a hosting server as is.

This publishing mechanism uses a single configuration file, .travis.yml, and is based on a GitHub + Travis CI + Asciidoctor container + GitHub Pages toolchain, an idea taken from GitHub Pages Deployment.

Each commit pushed to a pre-configured branch (such as master, devel, or stable) containing a .travis.yml automatically triggers a document build, so you do not need an extra tool installed locally in order to publish an update to the document. When the Asciidoctor container running in Travis CI successfully finishes the build, Travis CI pushes the resulting HTML (and, optionally, PDF) to a deployment branch (such as gh-pages or publish), and GitHub Pages then publishes the HTML (and PDF) from the deployment branch to the desired URL (for instance, my-project.github.io/my-document).

This publishing mechanism is used to publish the Community Collaboration Guide from https://github.com/redhat-documentation/community-collaboration-guide.

Currently, the best method for proposing a change to the Community Collaboration Guide is to open an issue in the community-collaboration-guide GitHub repository.

You must be a member of the GitHub community-collaboration-guide repository. Request to join by emailing your GitHub username to ccs-upstream@redhat.com.

We encourage contributions to the Community Collaboration Guide. In particular, you can share your experiences in the following areas:

Fork the community-collaboration-guide upstream repository to create a fork under your own GitHub ID. This allows you to work on multiple pieces of content and push changes to branches in your local GitHub instance. When you are ready, you can request the changes be merged from your local fork into the upstream repository.

When using the SSH address for creating a clone, you need to add an SSH Key to GitHub. See the article Generating an SSH Key for more information.

Clone the repository. Your fork is the origin location for your local files.

After you have forked and cloned the upstream repository, connect it to your local fork by adding the upstream repository as a remote.

Fetch the latest source from the upstream repository. Note that using the git fetch command to obtain the latest copy of the source does not actually "put" the content on your local fork until you perform some other action, such as creating a branch.