Documentation for ASEE public APIs

Both documentation and guidelines are livinig documents open for contribution. Please ask any questions, dillemas, suggestions as github issues on this repository so others can benefit from recorded answers and discussion.

API Definition and Documentation Guidelines

Be sure to check both definition guidelines and documentation guidelines before you start writing specifications and documentation.

Writing Style

For general software documentation writing style and terminology, see the Microsoft Manual of Style.

Writing Tools

Following tools can help you write swagger and markdown text files:

• Api Studio web based yaml+swagger json+swagger
• Stack Edit web based markdown
• Visual Studio Code desktop markdown yaml

These are just suggestions, you are wellcome to use different tools or work in notepad if you prefer

Client library generator

Use Autorest to generate client library in C# and verify that generated code compiles properly.

Organization of source files

See how we organize documentation source files.

Build process

This is how we produce documentation site from source files:

1. Documentation writer checks-in yaml / markdown file
2. Build script converts swagger files from yaml to json
3. Build script generates static html from markdown using templates and pretzel tool
4. Build script publishes documentation site