Hi! Since documentation and website are currently in a horrible old condition, I thought about launching a new site for documentation, probably as new subdomain docs.linuxsampler.org (or under www.linuxsampler.org/docs/).
Flat layout: Here is a mockup as an overall layout suggestion for that documentation site: http://download.linuxsampler.org/pix/screenshots/mockup_docs_linuxsampler_org.png I am not the biggest fan of flat layout (especially since many companies already brought their layouts on "kindergarten flat" level), but in this case I though it makes sense. The suggested font used is a free one called "Ek Mukta", a modern sans serif font, providing a large set of font weights (ultra thin, thin, normal, semi bold, bold, ultra bold) and is well readable for human beings. You can preview this font in various styles i.e. on Google Fonts. Visual structure: - On the very top there is a hard coded dark gray bar with global links to important topics, i.e. links to the documentation entry points for our various apps, links to other servers, etc. - Just below the hard coded link bar, there is an auto generated light gray navigation bar, showing the current overall tree location on the documentation web server, which allows to jump back to some parent article. - Main block to the right with white background; the current article. - On the very left there is table of contents of the currently visible article. The user may auto scroll the current article by clicking on an item of that table of contents, and vice versa the table of contents automatically highlights the currently visible paragraph when the user scrolls the article on the right. - Hard coded footer on the very bottom, copyright notice, and probably some more links, etc. File & Directory Structure: My suggestion is to write the actual articles as stripped-down HTML input files, without "html" tag, without "body" tag, root tag would be an "article" tag, everything inside that root "article" tag would be regular html (and CSS) with all its possibilities. The html input files would be managed on svn and our build server would auto generate the actual (static) website by processing those input html files whenever somebody commits something new, thus auto generating especially navigation bar, table of contents, website header and footer for each page. Each input HTML file would be named "index.html" and thus being in its own directory on svn. The resulting input directory names and input directory structure would be taken to auto generate the navigation structure of the website. Besides the actual articles files, there would be couple other input files defining the overall look of the website globally, separate from the individual articles. An example input article file based on these suggestions might look like this: <article title="Conditional Statements"> <p>Conditional statements are bla bla bla.</p> <h3>A deeper view</h3> <p>Bla bla bla.</p> <h3>And even more</h3> <p>Bla bla bla. <a href="foo">Read more about topic foo ...</a></p> <h3>Starting the hack</h3> <p> Bla bla bla. <code lang="nksp"> on init declare $a := "bla" declare @h := "Hello " declare const @w := "world!" message(@h) message(@w) end on </code> bla bla bla bla. </p> <h2>The next level</h2> <p>Bla bla bla.</p> </article> So table of contents of an article would be auto generated by reading the regular "h2" and "h3" html tags. Article name and thus website page title would be defined by the "title" attribute of the "article" tag. Syntax highlighting for example code blocks would also be auto generated. The "lang" attribute of the "code" tag would be mandatory to give the build server an idea which programming language was meant for being able to produce correct syntax highlighting. Opinions, suggestions and tomatoes appreciated! CU Christian ------------------------------------------------------------------------------ Dive into the World of Parallel Programming. The Go Parallel Website, sponsored by Intel and developed in partnership with Slashdot Media, is your hub for all things parallel software development, from weekly thought leadership blogs to news, videos, case studies, tutorials and more. Take a look and join the conversation now. http://goparallel.sourceforge.net/ _______________________________________________ Linuxsampler-devel mailing list Linuxsampler-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/linuxsampler-devel
