concerted-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gaurav Shukla <>
Subject Documentation Format
Date Tue, 20 Oct 2015 12:26:35 GMT
Before we begin documenting anything I would like to discuss the format for

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.

{"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>]

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
Phone: +91-837-584-7862

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message