concerted-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Ramdoss, Vijayakumar" <Vijayakumar.Ramd...@emc.com>
Subject RE: Documentation Format
Date Tue, 20 Oct 2015 20:10:18 GMT
+1

Regards
Vijay Ram 

Enterprise Data Platforms
Vijayakumar.Ramdoss@emc.com 
Mobile: +1-508-667-9874 |Office:  +1-508-898-4950

-----Original Message-----
From: Jake Farrell [mailto:jfarrell@apache.org] 
Sent: Tuesday, October 20, 2015 4:06 PM
To: dev@concerted.incubator.apache.org
Subject: Re: Documentation Format

agree, +1 markdown

-Jake

On Tue, Oct 20, 2015 at 2:45 PM, Julian Hyde <jhyde@apache.org> wrote:

> +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