[jira] [Commented] (TS-2446) Document how to document

["ASF subversion and git services (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/TS-2446?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15143099#comment-15143099 ] 

ASF subversion and git services commented on TS-2446:
-----------------------------------------------------

Commit cbb0d7277a9d672764241c4d62e4c7bcb7987130 in trafficserver's branch refs/heads/master from [~jsime]
[ https://git-wip-us.apache.org/repos/asf?p=trafficserver.git;h=cbb0d72 ]

TS-2446: dev guide section on documenting plugins


> 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
>            Assignee: Jon Sime
>             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.3.4#6332)