Miles Libbey created TS-2446:
--------------------------------
Summary: Document how to document
Key: TS-2446
URL: https://issues.apache.org/jira/browse/TS-2446
Project: Traffic Server
Issue Type: Improvement
Components: Documentation
Reporter: Miles Libbey
Our documentation system has a very large learning curve. Writers need to
learn reStructured text and Sphinx and our unique conventions/hooks/whatever.
Without documentation, writers have to view many doc source code to attempt to
comprehend what those conventions are. Similarly, these conventions prevent
standard reStructured text from rendering cleanly (for instance,
http://rst.ninjs.org/ shows tons of errors for any given doc file we have --
http://rst.ninjs.org/?n=aa8dc0bc3e337df7a2b5e14757debc81&theme=basic). Lastly,
we should provide explicit, step by step instructions on how to get a local
version of sphinx up and running that a non developer can follow.
We need to document:
- what are all the trafficserver specific hooks/conventions?
- when should they be used?
- how they should be used?
- how to preview a change without pushing to production?
For instance, Igor noted as part of reviewing
https://issues.apache.org/jira/browse/TS-2183 :
"General: all of the CAPSLOCK words should be put in the glossary"
- how does one mark a term in the doc as having a glossary item?
- where (what file) would the item's definition go?
- what is the structure of that definition?
Some other specific markup that needs explanation:
:ts:cv:
ts:const:
ts:git:
Similarly, it's also not clear to me when to choose markup like
`proxy.config.http.server_ports`_ versus :index: vs :ts:cv: vs :ref: etc.
--
This message was sent by Atlassian JIRA
(v6.1.4#6159)
