Documentation (Tech Writers)

Table of Contents

• Zero-Day Plan for Technical Writers
• Intro - Our Journey
• Contributing - IMPORTANT!
• REST API Documentation
  • Auto-Generating Docs
  • Deploying Docs to gh-pages
• Internal (Non-Mobile) API Documentation
• Future Goals

Zero-Day Plan for Technical Writers

Familiarize yourself with the follow technologies:

• REST API design and documentation
• ApiDocJS - for automatic documentation generation from inline code
• gulp for build automation to run documentation libraries and deploy generated docs
• JSDOC - this has not been implemented yet, but our documentation style for the Non-Mobile REST API follows their standards.
• Learn about fork and pull-request model for github when contributing. See the Contributing section.

For the Technical Lead,

• Assign Technical Writers to the github organization to the Architect and Technical Writer group. This will give them read-only access to the repo, so they must use a fork and pull-request model to contribute their documentation.

---

Our Journey from Tool to Tool

First off, we always delegate task via our Trello task board. Each individual is assigned a part of the code to document base.

We actually worked very closely with the Architect team, so closely that the teams were both merged and we often interchanged task. Sometimes architects would help document the app, while some tech writers would join in the design meetings to contribute their ideas.

Our first tool was Google Docs, while the Architect team was planning out the API they also wrote some general API documentation. At this point, we had no idea how to design a REST API let alone document it, so the documentation very in depth. It only included some url paths like /api/business/

After a while the architect team finalized the system design of the API which was still ever changing, we decided to move the documentation to the Github Wiki. There were many cons in using the Github Wiki, if you know anything about github's markdown, there are no custom colors for fonts. This made it horrible to read and distinguish an API method like GET POST UPDATE DELETE PATCH

So we decided to make our own, but soon realized there's a better option out there apidocjs which has many features like converting comments in the source code into a web page for documenting a REST API.

You can see the results of the api documentation here: http://cse112-goldteam.github.io/web-app/

---

Contributing - IMPORTANT!

When contributing anything, including documentation, follow the fork and pull-request model this is vital for maintain a clean and healthy repo with out crazy merge issues and allows the maintainer of the repository to locate issues easily.

---

REST API Documentation

See the newest api docs LIVE HERE!

We decided to use two gulp's library to auto-generate the documentation gulp-apidoc and then deploy it gulp-gh-pages. As a plus, we made gulp open up a browser of the page the documentation is deployed to with a library called gulp-open.

Auto-Generating Docs

Documentation like the following will be scanned by apidocjs and auto-generate a nice web page containing the documentation:

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

To learn more about the syntax used to do inline documentation. See apidocjs.

Assuming you cloned the webapp project and have the app setup, to generate the documentation locally (this is useful to see small changes as you update the documentation without deploying it every time) from the inline documentation that you've done, you can run in the terminal:

gulp apidoc

Then you'll see a folder in the root directory /apidocs and inside is the index.html file that will show the REST API documentation.

Deploying the Docs to gh-pages

If you're confident that your api is ready to show the world (developers) simply run the follow command :

gulp doc-deploy

which generates the doc and deploy it simultaneously

---

Internal (Non-Mobile) API Documentation

These are comments not relating to the REST API, which are used internally for the web app. In the future it would also be great to automatically generate documentation for these comments as well using jsdoc. We followed their guidelines so it should be easy to integrate into gulp.

/**
 * Takes an HTTP Basic Auth String and returns the username and password parts of it.
 *
 * @param authString The auth string with "Basic " already removed from beginning,
 * @returns {Object|Boolean} An object with fields `email` and `password` or the value `false`
 * indicating that the auth string is not valid.
 */
function decodeAuthString(authString) {
    ...
}

---

##Future Goals

Documentation generation for other code besides the REST API using jsdoc.