You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@concerted.apache.org by Gaurav Shukla <gs...@gmail.com> on 2015/10/20 14:26:35 UTC
Documentation Format
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
Re: Documentation Format
Posted by Atri Sharma <at...@apache.org>.
+1
On Wed, Oct 21, 2015 at 12:15 AM, Julian Hyde <jh...@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 <gs...@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
>
>
--
Regards,
Atri
Apache Concerted
RE: Documentation Format
Posted by "Ramdoss, Vijayakumar" <Vi...@emc.com>.
+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 <jh...@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 <gs...@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
>
>
Re: Documentation Format
Posted by Gaurav Shukla <gs...@gmail.com>.
Then we would need some script to get text from markdown and convert it to
json for indexing and probably we could implement it as a precommit hook or
as task in some task runner like grunt.
I am already using grunt for builing deployment version of website I could
include a task to be run on Documentation folder and get json from markdown.
Views please ?
On Wed, Oct 21, 2015 at 1:36 AM, Jake Farrell <jf...@apache.org> wrote:
> agree, +1 markdown
>
> -Jake
>
> On Tue, Oct 20, 2015 at 2:45 PM, Julian Hyde <jh...@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 <gs...@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
> >
> >
>
--
Regards !
Gaurav Shukla
gauravshukla.xyz
Phone: +91-837-584-7862
Re: Documentation Format
Posted by Jake Farrell <jf...@apache.org>.
agree, +1 markdown
-Jake
On Tue, Oct 20, 2015 at 2:45 PM, Julian Hyde <jh...@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 <gs...@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
>
>
Re: Documentation Format
Posted by Julian Hyde <jh...@apache.org>.
+1 markdown
Make things easier for humans - lower the bar to contributions.
> On Oct 20, 2015, at 5:26 AM, Gaurav Shukla <gs...@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