Documentation Requirements for ECR

When a project is added to the ECR, the SDO team will work with you to make sure that all the required artifacts are in place. These artifacts serve two purposes. The primary purpose is to provide documentation that shows that your project went through the governance process. This is a critical step. If your code cannot be shared due to contractual requirements, then Leidos could be adversely affected. The other purpose for these artifacts is to connect your documentation to the EDR - the Enterprise Document Repository.

It's important that your repository is set to have "community" as the default branch.

Minimal Documentation Requirements

To be minimally compliant, should only take about 15 minutes. Your artifacts can live in your master branch, or they can live in the community branch of your ECR based repository. Selecting the branch to place your artifacts, is based on your own preference. In general, put them in the master, or develop branch of your main (original) repository, if you want to maintain them as part of your project over time. Place them in the community branch on ECR if you don't want them in your project. If you follow the on boarding instructions, you will have a community branch created as part of your ECR project setup. The following steps will follow the community branch approach.

Make sure you have the community branch checked out
1. ```
git checkout community
```
Create a docs folder. It can be any name you want, however, its best if it is a new folder
1. ```
mkdir docs
```
Add the templates from the ECR into the docs folder
1. index.rst
2. governance.rst
Add your governance.xlsx file to the docs folder
1. Note: Your file will have a different name - please add the file using the name as provided to you.
Add your files to git
1. ```
git add docs
```

Commit your files

git commit -a -m "added required ecr artifacts"

And push to ECR
1. ```
git push <remote name> community
```

Once you have done this, you can notify the SDO team, and we will take care of integrating your docs into the EDR.

There was one assumption that we made. We assume that you have a README.md file in the top level of your project. If you do - great, then we are good to go. If you don't, then you should take some time to provide some additional documentation.

Medium Documentation Requirements

This is probably a good time to spend a few minutes to read the EDR Primer. The Primer has a nice discussion of the different files that make up the set of documentation. Your project README.md may be short and sweet, or may be incredibly detailed. Usually, that file will contain information about how to build or deploy your application. Making sure that the markdown used in the README.md is correct, and that the Section marks and code blocks are good, really helps to communicate to other developers. You can use ECR / Bitbucket to see your README.md file. If you want to see what the file will look like in EDR, you can follow the instructions for creating your own document viewer.

Having a well defined README.md file, that works well inside of the EDR will really help the community understand what your project is all about, and how they can make use of your code or artifacts.

If you need a template for a README.md file, you can find one here.

Advanced Documentation Requirements

Advanced is probably not the right word. These should have been labeled Good | Better | Best instead. Your README.md file is now beautiful markdown, with lots of great information. There still are probably a few things missing. Perhaps a paragraph on why this code is being shared? Maybe a rundown of the APIs that are available, or tips on maintenance etc. You can also help by providing input to the EDR Taxonomy, and have your document indexed into the Taxonomy page.

This is not difficult, and its really not Advanced, its just Best, it does require a little bit of time. 5 minutes or an hour? It's up to you. It all starts with the index.rst file that you added earlier.

Add Your Taxonomy

To add the taxonomy, simple add taxonomy tag lines to your index.rst file, between your Project name at the top, and the first .. toctree:: is fine, but they can go anywhere. For example,

Project Name
============

.. taxonomy:: java
.. taxonomy:: security
.. taxonomy:: api

.. toctree::
   :maxdepth: 2

   ./governance

The format of the .. taxonomy:: is really important. The dots should be at the beginning of the line, with no spaces before the first dot. What comes after is up to you. What is most important in categorizing your application? Infrastructure, programming language, deployment context? It's up to you. With your taxonomy tags added to your index.rst file, your application will be included on the Taxonomy page in EDR.

Organize Your Documentation

Notice the use of the toctree in the example documentation. The toctree is the Table Of Contents tree. Its one of the many Sphinx Document Directives available in reStructuredText (RST) in the EDR. The Primer has some details on how to use them. The power comes in being able to create sub documents that are automatically included in your documentation. You can create installation guides, user guides, deployment guides etc, using either markdown or rst, and then have those documents managed by the EDR.

One important note - documents in the toctree do not use their file extensions, use ./governance and not ./governance.rst

So thats it! How much documentation, beyond the minimal requirement is up to you. But, the better the documentation, the greater success that people will have using your shared code. That will mean fewer emails and 2am phone calls - jk.