1.8 KiB
Style guide for markdown docs for AyaNova
Title usage
Titles need to be used with navigation in mind as they appear in the index and to the right in the page toc. So put titles in that users would be looking for specifically
Usage
page title
Major section subtitle
major subsection (optional)
this one is optional and used to subdivide a major section into parts
Field or specific item titles
These are very bold and should be used to draw attention to something similarly named in UI that user is looking for in docs
Titles should have a blank line under them then the text
Every page title is a level one title with one # symbol
DO NOT use fifth and sixth level titles unless absolutely necessary as they appear pretty drab and hard to read in the docs style being used
Navigation link descriptions
should be in a code block like this:
Click on Accounting then Service Rates to access the service rates form
Form / biz object related doc pages
form pages should follow identical format, the prototypical form is the acc-service-rates.md form, follow that guide
Images
use images sparingly and only when absolutely necessary to reduce docs size and save time in future updating outdated images Image should only be there when it's bringing value to what the user is looking at, for example when listing control types etc
it's not useful to put an image of every form since they are all almost identical, just snip out bits where they would add greatly to the xfer of knowledge or speed of uptake.
Links
Be very liberal with the use of internal links, users will get far more out of the docs when they can just click around while reading them without having to consule the index or try to figure out where a doc would be.