I have drafted a 'Standard Documents' page at: https://trac.kbase.us/projects/kbase/wiki/StandardDocuments It could probably be expanded to include what is required, but for now, it is a straw man. Miriam On 1/31/13 5:26 PM, "Nomi Harris" <[email protected]> wrote:

Thanks, Miriam, this is a much-needed reference page. Please go ahead and set it up and then people can edit if needed. Nomi Harris Project Manager, KBase

On Jan 31, 2013, at 12:46 PM, "Land, Miriam L." <[email protected]> wrote:

...

All,

The following started with a simple question from a developer, "Where do I put KBase documentation?" I couldn't find a clear and concise answer documented anywhere and it seems that the answer depends on what they mean by "documentation".

By poking around, I have concluded that user manuals are in the docs.git repo under user_manuals/<module_name> while the tutorials are also in the docs.git repo but under <module_name>/tutorials (flipped order). There are HTML files in the docs.git repo under <module_name>/API but it is not clear if there is any relationship to the HTML generated out of the type spec, and http://kbase.us/services/docs. I can't find documentation on who is responsible for writing some of these files and how these get propagated to the web (I've overheard oral instructions but little in writing). In addition to the type spec and multiple locations in the docs.git repo, we have the release notes which are part of the module repo with no specific file name and service descriptions developers supply through email at some point. I know we are evolving and defining things as we go along, but wouldn't you find this confusing at first?

Most developers eventually find out all this through email exchanges. Would anyone mind if I started a trac page that lists the mandatory files/information which we expect developers to produce? My first draft is below.

Miriam -------------------------------------- Type Spec -

* A controlled vocabulary for defining methods and types for a module. The type compiler converts this into a standard directory structure and stubs for necessary files. * Recommended naming convention is <module_name>.spec * https://trac.kbase.us/projects/kbase/attachment/wiki/API/Type_compiler.pd f

DEPENDENCIES

* A required file in the module top dir that lists dependencies * https://trac.kbase.us/projects/kbase/wiki/IndependentBuild

deploy.cfg

* Located in the module top dir and is needed for deployments * https://trac.kbase.us/projects/kbase/wiki/DeployCfgStandards

Makefile

* Located in the module top dir and is used in deployment, document generation, and testing * Example Makefile is part of the dev_container/docs/module.Makefile * Standard Makefile Targets - https://trac.kbase.us/projects/kbase/wiki/MakefileTargets

Release Notes ­

* A file in the module top dir with a name that a human would recognize as a release note (e.g., Release_notes_01Jan2013). * https://trac.kbase.us/projects/kbase/wiki/ReleaseNotesStyle

Technical Documentation ­

* information imbedded within the type spec document that describes methods and types. * The document is auto-generated when the type spec is complied and it is copied the /kb/deployment/services/<module_name>/webroot during deployment. * Can be accessed through http://kbase.us/services/docs/<module_name>. * https://trac.kbase.us/projects/kbase/wiki/DocStructures

User Manual ­

* Comprehensive documentation of methods and types. More detailed than technical documentation and more comprehensive that a tutorial. * Created from scratch and it committed to the docs.git repo under the user_manuals/<module_name> directory. * https://trac.kbase.us/projects/kbase/wiki/UserManuals

Tutorials ­

* A guided tour through a typical usage pattern for the module. * Created from scratch and it is committed to the docs.git repo under <module_name>/tutorials. * https://docs.google.com/document/d/1IxUo3kSWStE6rPYWemY_RmVyPA36lYNDa9QOp yxPvbg/edit (note, not at trac)

_______________________________________________ Release-team mailing list [email protected] https://lists.kbase.us/mailman/listinfo/release-team