concerted-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jake Farrell <jfarr...@apache.org>
Subject Re: Documentation Format
Date Tue, 20 Oct 2015 20:06:19 GMT
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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message