[
https://issues.apache.org/jira/browse/TS-2446?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Leif Hedstrom updated TS-2446:
------------------------------
Fix Version/s: Docs
> 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
> Fix For: Docs
>
>
> 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)
