I welcome any attempts to improve on the list. I think user's would love to see explanations of anything automatically generated or pushed to the web. They like to understand the consequences of choices they make. Miriam On 1/31/13 3:49 PM, "Thomas Brettin" <[email protected]> wrote:
This looks great, there is one issue, that is the automatically generated documentation that we are planning to extract from the --help flag to all commands. This will be deployed to webroot and injejested by Neal into the developer's zone.
Tom
On Jan 31, 2013, at 2: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
Thomas Brettin 865-603-7760 (cell) [email protected]