Documentation

[jstayton]

I see a few different types of documentation:

1. General documentation that includes an overview, development setup, workflow, deployment, etc. Probably in the README.md. Here's an example of how I wrote it for Monk ID JS.
2. Higher-level component documentation. Like documenting the CMS' API or a specific module. As @mcordell recommended, maybe we could utilize GitHub's wiki functionality?
3. Code documentation. Each language/framework-specific convention file can specify the recommended tool/library, but generally I think we should prescribe
   • 100% coverage,
   • easily generated,
   • and ignored by version control.
4. Developer/API documentation. Not every project will have this, but when a developer can integrate with the project, it should include this. Maybe include a getting started guide with examples? Maybe pick a tool for documenting APIs, if such a thing exists?

[shanebonham]

I also like @mcordell's idea of generating Dash docset feeds.

[mcordell]

BTW since our convention talk, when I am trying to understand a feature in the CMS I am keeping notes and currently storing them in the wiki. They aren't super detailed, but I feel like they could definitely save time. Obviously I'll move them if this idea is no good or we are going to use the wiki for something else.

[rickyatmonk]

I experimented with the Wiki today:

Pros

• markdown
• In GH
• clonable

Cons

• I can't comment in the Wiki
• I can't figure out how to organize pages nicely. It's just a dump in the sidebar.

[rickyatmonk]

Page organization can be handled with a Table of Contents page and custom sidebars.

[jstayton]

It seems like using the wiki for higher-level / more in-depth documentation is working out well. Anyone think we should explore other options?

Or any additional ideas in general before I turn this into a formal pull request? I think there are some things we don't know yet — like what to use for API documentation — but we can leave that out for now and add it once we know.

@shanebonham @mcordell @rickyatmonk @lefthand @etdebruin @kennykaye

[shanebonham]

:thumbsup:

[rickyatmonk]

:+1: to make a PR

[mcordell]

:thumbsup:

Any ruling on the dash doc sets?

[jstayton]

@mcordell:

Any ruling on the dash doc sets?

Totally cool with me. Anything we need to do to make it work that should be mentioned here?

[mcordell]

Yeah I might have to explore further, but if recall correctly it requires the OSX command line tools so it probably cannot be integrated into the deploy process. I'll try to think of another solution.

[shanebonham]

For PHP, this leads one to this which kinda/sorta seems like it could run during production deploys.

[mcordell]

Yeah you can generate the HTML, HTML->docset is the step that require OSXs docsetutils

[jstayton]

A few more...

1. Code documentation should appear on the line(s) before the code being documented.
2. Proper spelling, grammar, and punctuation should be used. Be a good writer.
3. All functions and methods should be documented, including parameter(s), return value(s), and exception(s) that can be thrown/raised.
4. While code documentation is generally good, it should not be used as a crutch to mask bad code. As Jeff Atwood says, "You should always write your code as if comments didn't exist. This forces you to write your code in the simplest, plainest, most self-documenting way you can humanly come up with."

Recommended README outline:

Title
=====

[Badges]

One sentence description.

*   [Link to documentation]
*   [Or staging and production]
*   [Or anything of importance]

Overview
--------

Explain how things work. For an app, give a high-level overview of the system. For a library, explain how to install, configure, and integrate.

### Use

#### Sections

#### As

### Necessary

Development
-----------

Explain how to setup the development environment. List prerequisites like languages and databases that can't be installed automatically, as well as dependencies that can. List the commands for building documentation, running tests, executing tasks, etc.

Deployment
----------

Explain and list the commands for deploying, restarting services, etc.

[shanebonham]

All functions and methods should be documented, including parameter(s), return value(s), and exception(s) that can be thrown/raised.

Would you include vanilla getters and setters with this?

[jstayton]

In non-generated / custom classes, I do document them. In something like CMS models, I wouldn't.