Idea is to have a holy grail documentation system , which can vastly improve the accessibility/usage of documents in a company/education institute etc..
Key requirements to satisfy:
- fast to access ( most of the content as one web page with href # ?)
- well organised ( easy to comprehend )
- easy to author ( )
- easy to edit ( on the page itself , with a popup window? / Ajax call to server )
some good templates to consider
1/ OpenJDK http://openjdk.java.net ( Adv: no flicker , huge prod. tested documentation sytle ( big openjdk community )
- compare with SVG open 2011 workshop page ( no flicker, no links )
2/ level TAB base http://keith-wood.name/gChart.html ( all content single page )
3/ Sphinx ( for content Authoring ) : http://sphinx.pocoo.org/tutorial.html#documenting-objects ( it has server , Docutil )
- used by our fav. PhD student
4/ wikia : http://japaneserecipes.wikia.com/wiki/Azuki_Ice_Cream
- this this kind of too many edit may not be good for Programmers
- JDOM http://jdom.org/docs/faq.html ( some other simple Styles )
- http://planetjdk.org/
features of above Doc Styles:
1/ openJDK
http://openjdk.java.net/guide/producingChangeset.html#merge
- has TOC for this kind of docs ( improvement: we may need TOC as open/Collapse DIV to see contens instead of click to new page , see Quora.com comments collapse div )
http://openjdk.java.net/projects/jdk7/builds/
- menu at top of the page << features build ...>> this is one kind of template for TOC lists
- Build Google calender , nice calender integration when involved big teams
2/ JQuery gcharts:
- improvement: if used for TOC style documentation , have TOC section once user clicks on ' 2nd level tab' , and also 'top' image icon on each section so that user can go top TOP of the page any time with our much of mouse click wheel UP .
3/ Sphinx:
Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
Docutils is an open-source text processing system for processing plaintext documentation into useful formats, such as HTML or LaTeX. It includes reStructuredText, the easy to read, easy to use, what-you-see-is-what-you-get plaintext markup language.
Key requirements to satisfy:
- fast to access ( most of the content as one web page with href # ?)
- well organised ( easy to comprehend )
- easy to author ( )
- easy to edit ( on the page itself , with a popup window? / Ajax call to server )
some good templates to consider
1/ OpenJDK http://openjdk.java.net ( Adv: no flicker , huge prod. tested documentation sytle ( big openjdk community )
- compare with SVG open 2011 workshop page ( no flicker, no links )
2/ level TAB base http://keith-wood.name/gChart.html ( all content single page )
3/ Sphinx ( for content Authoring ) : http://sphinx.pocoo.org/tutorial.html#documenting-objects ( it has server , Docutil )
- used by our fav. PhD student
4/ wikia : http://japaneserecipes.wikia.com/wiki/Azuki_Ice_Cream
- this this kind of too many edit may not be good for Programmers
- JDOM http://jdom.org/docs/faq.html ( some other simple Styles )
- http://planetjdk.org/
features of above Doc Styles:
1/ openJDK
http://openjdk.java.net/guide/producingChangeset.html#merge
- has TOC for this kind of docs ( improvement: we may need TOC as open/Collapse DIV to see contens instead of click to new page , see Quora.com comments collapse div )
http://openjdk.java.net/projects/jdk7/builds/
- menu at top of the page << features build ...>> this is one kind of template for TOC lists
- Build Google calender , nice calender integration when involved big teams
2/ JQuery gcharts:
- improvement: if used for TOC style documentation , have TOC section once user clicks on ' 2nd level tab' , and also 'top' image icon on each section so that user can go top TOP of the page any time with our much of mouse click wheel UP .
3/ Sphinx:
Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
Docutils is an open-source text processing system for processing plaintext documentation into useful formats, such as HTML or LaTeX. It includes reStructuredText, the easy to read, easy to use, what-you-see-is-what-you-get plaintext markup language.
No comments:
Post a Comment