concerted-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Julian Hyde <jh...@apache.org>
Subject Re: Documentation Format
Date Tue, 20 Oct 2015 18:45:38 GMT
+1 markdown

Make things easier for humans - lower the bar to contributions.



> On Oct 20, 2015, at 5:26 AM, Gaurav Shukla <gshukla66@gmail.com> wrote:
> 
> Before we begin documenting anything I would like to discuss the format for
> documentation.
> 
> Our Website uses Angular Js to render dynamic content like news,
> Releases,contributers and all other stuff.
> 
> So I was thinking of storing the complete documentation in json format.
> 
> eg.
> {"version": [<The version for which this doc is created (same doc can be
> for more than 1 version)>],
> "component":[ <eg: transaction manager,resource manager, etc>]
> "content":{the
>                main
>                text
>                goes
>                here
>                },
> }
> 
> This is certainly not the most user friendly way to store docs but if
> stored in this format the documentation can be indexed as it is in elastic
> search and can also be rendered on website without any hassle.
> 
> Although one drawback of this approach is markup will have to be stored in
> content part and will also be indexed.
> 
> Markup would be minimum just a few bold,italic ,underline tags
> 
> 2. Storing As HTML
> 
> I don't see any advantage apart from direct rendering on github and website
> but for documents to be searchable we will need some script to convert it
> to json and index in elastic search
> 
> 3. Storing in markdown
> 
> This format is most user friendly but has same issues as html.
> 
> I am not sure how common it is to store docs in json or even discuss about
> format of documentation. So any help in this area would great.
> -- 
> Regards !
> Gaurav Shukla
> gauravshukla.xyz
> Phone: +91-837-584-7862


Mime
View raw message