Christian Schoenebeck
2015-01-26 17:53:25 UTC
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:
Loading Image...
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
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:
Loading Image...
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