Skip to end of metadata
Go to start of metadata

Developer Guide

Every component should a Developer Guide. Content guidelines:

  • this should be very technical, aimed at people who want to help develop the components
  • this should be how the component does what it does, not a requirements document of what the component should do
  • this should contain what language(s) and frameworks are used, with versions
  • this should contain how to obtain the code, where to look at work items (Jira tickets), how to get started developing 

Below is an example that you can use to start writing your Developer Guide. Your Developer Guide should have much more content than this example. Consult the Style Guide for writing tips.

Notethe docs project has the ability to generate a page based on a swagger.json file.  See https://docs.acumos.org/en/latest/docs-contributor-guide/documenting-apis.html


Example Developer Guide
.. ===============LICENSE_START=======================================================
.. Acumos
.. ===================================================================================
.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
.. ===================================================================================
.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
.. under the Creative Commons Attribution 4.0 International License (the "License");
.. you may not use this file except in compliance with the License.
.. You may obtain a copy of the License at
..  
..      http://creativecommons.org/licenses/by/4.0
..  
.. This file is distributed on an "AS IS" BASIS,
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.. See the License for the specific language governing permissions and
.. limitations under the License.
.. ===============LICENSE_END=========================================================

================================
<COMPONENT NAME> Developer Guide
================================

Overview
========
Provide an overview of the component. To be clear, the target
audience for this guide is a developer who will be developing
code for this feature itself.


Architecture and Design
=======================

Provide information about feature components and how they work together.
Also include information about how the feature integrates with
Acumos. An architecture diagram could help. This may be the same
as the diagram used in the user guide, but it should likely be less
abstract and provide more information that would be applicable to a
developer.
	
Technology and Frameworks
=========================
Provide a list of the development languages, frameworks, etc 


Project Resources
=================

Provide gerrit, Jira info,  JavaDoc (javadoc.acumos.org) if relevant, link to REST API documentation, etc.
For example:


- Gerrit repo: <name of gerrit repo>
- `Jira <https://jira.acumos.org>`_  <component name>
 
Development Setup
=================


How to Run
==========
Provide steps to package and deploy your component, both for local testing
and for testing on a server.

How to Test
===========
Provide information how to test your component




Key APIs and Interfaces
=======================

Document the key things a developer needs to know about your component's APIs. For some components,
there will only be one logical grouping of APIs. For others there may be
more than one grouping.

API Group 1
-----------

Provide a description of what the API does and some examples of how to
use it.

API Group 2
-----------

Provide a description of what the API does and some examples of how to
use it.


User Guide

If your component has a UI or needs to be configured, your component needs a User Guide.

User guide content guidelines:

    • if the guide contains sections on third-party tools, is it clearly stated why the Acumos platform is using those tools? are there instructions on how to install and configure each tool/toolset?
    • does the guide state who the target users are? for example, modeler/data scientist, Acumos platform admin, marketplace user, design studio end user, etc
    • if there are instructions, they are clear, correct, and fit for purpose
    • does the guide contain information more suited for a different guide?
    • a user guide should be how to use the component or system; it should not be a requirements document
    • a user guide should contain configuration, administration, management, using, and troubleshooting sections for the feature.

Below is an example that you can use to start writing your User Guide. Your User Guide should have much more content than this example. Consult the Style Guide for writing tips.

Example User Guide
.. ===============LICENSE_START=======================================================
.. Acumos
.. ===================================================================================
.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
.. ===================================================================================
.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
.. under the Creative Commons Attribution 4.0 International License (the "License");
.. you may not use this file except in compliance with the License.
.. You may obtain a copy of the License at
..  
..      http://creativecommons.org/licenses/by/4.0
..  
.. This file is distributed on an "AS IS" BASIS,
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.. See the License for the specific language governing permissions and
.. limitations under the License.
.. ===============LICENSE_END=========================================================

===========================
<COMPONENT NAME> User Guide
===========================

Target Users
============
Provide information on who your users are: Modelers, administrators, developers, etc
	

Overview
========

Provide an overview of the component and the use case.

Architecture
============

Provide high-level information about the feature components and how it fits 
into the Acumos platform

.. note:: Please *do not* include detailed internals that somebody
          using the feature wouldn't care about. 


How to Use <COMPONENT NAME> 
===========================

Describe how to use the component 



Tutorial
========

*optional*

If there is only one tutorial, you can include it in the User Guide.
If there are several tutorials, it is better to create separate guides
for each one.

<Tutorial Name>
---------------

Ensure that the title starts with a gerund. For example using,
monitoring, creating, and so on.

Overview
^^^^^^^^

An overview of the use case.

Prerequisites
^^^^^^^^^^^^^

Provide any prerequisite information, assumed knowledge, or environment
required to execute the use case.

Instructions
^^^^^^^^^^^^

This section should be step by step instructions on how to use
the component. You can include screenshots and code samples
to make the instructions clearer.



Installation Guide

Example Installation Guide
.. ===============LICENSE_START=======================================================
.. Acumos
.. ===================================================================================
.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
.. ===================================================================================
.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
.. under the Creative Commons Attribution 4.0 International License (the "License");
.. you may not use this file except in compliance with the License.
.. You may obtain a copy of the License at
..  
..      http://creativecommons.org/licenses/by/4.0
..  
.. This file is distributed on an "AS IS" BASIS,
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.. See the License for the specific language governing permissions and
.. limitations under the License.
.. ===============LICENSE_END=========================================================

===============================================
<PLATFORM OR COMPONENT NAME> Installation Guide
===============================================



Overview
========

Add overview of the platform or component. 

Prerequisites
=============

* Hardware Requirements
* Software Requirements

Preparing for Installation
==========================

Include any pre configuration, database, or other software downloads
required to install <feature>.

Installation
============

Step by step instructions

Verifying the Installation
==========================

Describe how to verify the installation

Troubleshooting
===============

*optional*

Text goes here.

Post Installation Configuration
===============================

Post Installation Configuration section must include some basic
(must-do) procedures if any, to get started.

Mandatory instructions to get started.

* Logging in
* Getting Started
* Manual Configuration 

Upgrading From a Previous Release
=================================

Text goes here.

Uninstalling
============

Text goes here.





 

  • No labels