[
http://jira.magnolia-cms.com/browse/DOCUM-37?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Antti Hietala updated DOCUM-37:
-------------------------------
Description:
*(this issue is currently being edited, don't consider the following as actual
requirements)*
We'd like to gather some ideas, thoughts and feedback on the current
documentation site layout, and propose a few improvements, and/or a completely
new design.
The points below might not all directly be related to actual design. Some might
be related to "usability" (as in, adding a "feature" to the site, templates,
etc) or solved by implementing/fixing features in the wiki rendering module,
for example. We'll reference to other Jira issues when appropriate.
h3. Current "issues" with the current layout
* Feels "outdated"; not very "fresh" or "modern".
h3. Things we like about the current layout
* Clean and simple
* Common fonts that are clean and readable.
* Presentation is not cluttered by unnecessary color or imagery.
h3. Further ideas or requirements
* Examples (which may or may not contain code samples) could be differentiated
from the rest with background color.
* Code blocks. Visually separate from text flow. Fixed-width font. Syntax
highlighting (Java, Freemarker, JSP, XML, HTML, none).
[Pyramid|http://docs.pylonsproject.org/projects/pyramid/1.1/narr/i18n.html] has
clean-looking code blocks. (Antti)
* Icons: we currently use a couple of icons in content - would be great if they
were consolidated:
** external links
(!http://documentation.magnolia-cms.com/dms/layout/external-link-ltr-icon.png!)
** (!), (on), ...
* Fonts: Font sizes don't display correctly on iPhone (DOCU-151). Implement a
font framework like [YUI 3: CSS
Fonts|http://developer.yahoo.com/yui/3/cssfonts/] to ensure that the foundation
is standardized.
* TOC. The wiki {toc} macro picks up headings only in the same paragraph where
the macro resides. I would like to see it improved to pick up headings from all
paragraphs on the page like the TOC in {{stkLargeArticle}}. It gets difficult
to edit a long article such as
[Imaging|http://documentation.magnolia-cms.com/modules/imaging.html] in a
single wiki paragraph, lots of scrolling in the dialog. The alternative is to
create a static TOC manually in HTML, which has the downside that it does not
react to changes in article structure. (Antti)
* List numbering. Unable to continue an ordered list if the numbering is
interrupted for example by a code block. This works quite well in Confluence
and in Jira - which both use wiki markup - but not on documentation site.
(Antti)
h3. Examples of documentation sites we like
* jQuery - http://api.jquery.com/jQuery.ajax/
* Sitepoint CSS reference - http://reference.sitepoint.com/css/syntax
* Google APIs -
http://code.google.com/apis/analytics/docs/tracking/asyncTracking.html (Antti)
** Lots of white space. Easy on the eye.
** Reasonable fonts and heading sizes. Base font: Arial, Helvetica, sans-serif.
Heading 1 170%, Heading 2 130%
** Max 3 levels of headings in one article
* http://flask.pocoo.org/docs/ (g)
* http://diveintohtml5.org/ - very book-like but I like the looks of it (g)
* http://www.alistapart.com/articles/css-floats-101/ (g) - is bordering and
over-coloring code samples really more efficient than switching to a
fixed-width font and some white space ? Also interesting are their navigation
(no hierarchy that I can see, but tags and categories)
h3. Examples of common content elements
* Table of contents (TOC):
[Imaging|http://documentation.magnolia-cms.com/modules/imaging.html]
* Screenshots: [Controls
reference|http://documentation.magnolia-cms.com/reference/controls.html]
* Tables: [Module
mechanism|http://documentation.magnolia-cms.com/reference/module-mechanism.html]
* Image gallery: [Architecture diagrams >
Instances|http://documentation.magnolia-cms.com/reference/architecture-diagrams/instances.html].
(This is really not pretty. Could use a gallery template without lightbox
transition effects.)
* Code blocks:
[Groovy|http://documentation.magnolia-cms.com/modules/groovy.html]
* Boxes:
[Warning|http://documentation.magnolia-cms.com/modules/categorization.html#Taggingdataitems],
[Info|http://documentation.magnolia-cms.com/modules/forum.html#PageInfodialog],
[Tip|http://documentation.magnolia-cms.com/modules/forum.html#Headerdialog].
Info and Tip look identical, should differentiate e.g. by making Info blue.
* Icons:
[Warning|http://documentation.magnolia-cms.com/modules/forum.html#Usage]
* Lists:
[Ordered|http://documentation.magnolia-cms.com/modules/forum.html#Createastylesheet]
(procedure, numbered),
[Unordered|http://documentation.magnolia-cms.com/modules/imaging.html#Features]
(bulleted)
h3. Documentation style guide
[Documentation style guide on the
wiki|http://wiki.magnolia-cms.com/display/DOCU/Documentation+Style+Guide]
was:
*(this issue is currently being edited, don't consider the following as actual
requirements)*
We'd like to gather some ideas, thoughts and feedback on the current
documentation site layout, and propose a few improvements, and/or a completely
new design.
The points below might not all directly be related to actual design. Some might
be related to "usability" (as in, adding a "feature" to the site, templates,
etc) or solved by implementing/fixing features in the wiki rendering module,
for example. We'll reference to other Jira issues when appropriate.
h3. Current "issues" with the current layout
* Feels "outdated"; not very "fresh" or "modern".
h3. Things we like about the current layout
* Clean and simple
* Common fonts that are clean and readable.
* Presentation is not cluttered by unnecessary color or imagery.
h3. Further ideas or requirements
* Examples (which may or may not contain code samples) could be differentiated
from the rest with background color.
* Code blocks. Visually separate from text flow. Fixed-width font. Syntax
highlighting (Java, Freemarker, JSP, XML, HTML, none).
[Pyramid|http://docs.pylonsproject.org/projects/pyramid/1.1/narr/i18n.html] has
clean-looking code blocks. (Antti)
* Icons: we currently use a couple of icons in content - would be great if they
were consolidated:
** external links
(!http://documentation.magnolia-cms.com/dms/layout/external-link-ltr-icon.png!)
** (!), (on), ...
* Fonts: Font sizes don't display correctly on iPhone (DOCU-151). Implement a
font framework like [YUI 3: CSS
Fonts|http://developer.yahoo.com/yui/3/cssfonts/] to ensure that the foundation
is standardized.
* TOC. The wiki {toc} macro picks up headings only in the same paragraph where
the macro resides. I would like to see it improved to pick up headings from all
paragraphs on the page like the TOC in {{stkLargeArticle}}. It gets difficult
to edit a long article such as
[Imaging|http://documentation.magnolia-cms.com/modules/imaging.html] in a
single wiki paragraph, lots of scrolling in the dialog. The alternative is to
create a static TOC manually in HTML, which has the downside that it does not
react to changes in article structure. (Antti)
h3. Examples of documentation sites we like
* jQuery - http://api.jquery.com/jQuery.ajax/
* Sitepoint CSS reference - http://reference.sitepoint.com/css/syntax
* Google APIs -
http://code.google.com/apis/analytics/docs/tracking/asyncTracking.html (Antti)
** Lots of white space. Easy on the eye.
** Reasonable fonts and heading sizes. Base font: Arial, Helvetica, sans-serif.
Heading 1 170%, Heading 2 130%
** Max 3 levels of headings in one article
* http://flask.pocoo.org/docs/ (g)
* http://diveintohtml5.org/ - very book-like but I like the looks of it (g)
* http://www.alistapart.com/articles/css-floats-101/ (g) - is bordering and
over-coloring code samples really more efficient than switching to a
fixed-width font and some white space ? Also interesting are their navigation
(no hierarchy that I can see, but tags and categories)
> Redesign of documentation.magnolia-cms.com
> ------------------------------------------
>
> Key: DOCUM-37
> URL: http://jira.magnolia-cms.com/browse/DOCUM-37
> Project: Documentation Module
> Issue Type: Task
> Components: templates
> Reporter: Grégory Joseph
> Assignee: Grégory Joseph
> Priority: Critical
> Fix For: 1.1
>
>
> *(this issue is currently being edited, don't consider the following as
> actual requirements)*
> We'd like to gather some ideas, thoughts and feedback on the current
> documentation site layout, and propose a few improvements, and/or a
> completely new design.
> The points below might not all directly be related to actual design. Some
> might be related to "usability" (as in, adding a "feature" to the site,
> templates, etc) or solved by implementing/fixing features in the wiki
> rendering module, for example. We'll reference to other Jira issues when
> appropriate.
> h3. Current "issues" with the current layout
> * Feels "outdated"; not very "fresh" or "modern".
> h3. Things we like about the current layout
> * Clean and simple
> * Common fonts that are clean and readable.
> * Presentation is not cluttered by unnecessary color or imagery.
> h3. Further ideas or requirements
> * Examples (which may or may not contain code samples) could be
> differentiated from the rest with background color.
> * Code blocks. Visually separate from text flow. Fixed-width font. Syntax
> highlighting (Java, Freemarker, JSP, XML, HTML, none).
> [Pyramid|http://docs.pylonsproject.org/projects/pyramid/1.1/narr/i18n.html]
> has clean-looking code blocks. (Antti)
> * Icons: we currently use a couple of icons in content - would be great if
> they were consolidated:
> ** external links
> (!http://documentation.magnolia-cms.com/dms/layout/external-link-ltr-icon.png!)
> ** (!), (on), ...
> * Fonts: Font sizes don't display correctly on iPhone (DOCU-151). Implement a
> font framework like [YUI 3: CSS
> Fonts|http://developer.yahoo.com/yui/3/cssfonts/] to ensure that the
> foundation is standardized.
> * TOC. The wiki {toc} macro picks up headings only in the same paragraph
> where the macro resides. I would like to see it improved to pick up headings
> from all paragraphs on the page like the TOC in {{stkLargeArticle}}. It gets
> difficult to edit a long article such as
> [Imaging|http://documentation.magnolia-cms.com/modules/imaging.html] in a
> single wiki paragraph, lots of scrolling in the dialog. The alternative is to
> create a static TOC manually in HTML, which has the downside that it does not
> react to changes in article structure. (Antti)
> * List numbering. Unable to continue an ordered list if the numbering is
> interrupted for example by a code block. This works quite well in Confluence
> and in Jira - which both use wiki markup - but not on documentation site.
> (Antti)
> h3. Examples of documentation sites we like
> * jQuery - http://api.jquery.com/jQuery.ajax/
> * Sitepoint CSS reference - http://reference.sitepoint.com/css/syntax
> * Google APIs -
> http://code.google.com/apis/analytics/docs/tracking/asyncTracking.html (Antti)
> ** Lots of white space. Easy on the eye.
> ** Reasonable fonts and heading sizes. Base font: Arial, Helvetica,
> sans-serif. Heading 1 170%, Heading 2 130%
> ** Max 3 levels of headings in one article
> * http://flask.pocoo.org/docs/ (g)
> * http://diveintohtml5.org/ - very book-like but I like the looks of it (g)
> * http://www.alistapart.com/articles/css-floats-101/ (g) - is bordering and
> over-coloring code samples really more efficient than switching to a
> fixed-width font and some white space ? Also interesting are their navigation
> (no hierarchy that I can see, but tags and categories)
> h3. Examples of common content elements
> * Table of contents (TOC):
> [Imaging|http://documentation.magnolia-cms.com/modules/imaging.html]
> * Screenshots: [Controls
> reference|http://documentation.magnolia-cms.com/reference/controls.html]
> * Tables: [Module
> mechanism|http://documentation.magnolia-cms.com/reference/module-mechanism.html]
> * Image gallery: [Architecture diagrams >
> Instances|http://documentation.magnolia-cms.com/reference/architecture-diagrams/instances.html].
> (This is really not pretty. Could use a gallery template without lightbox
> transition effects.)
> * Code blocks:
> [Groovy|http://documentation.magnolia-cms.com/modules/groovy.html]
> * Boxes:
> [Warning|http://documentation.magnolia-cms.com/modules/categorization.html#Taggingdataitems],
>
> [Info|http://documentation.magnolia-cms.com/modules/forum.html#PageInfodialog],
> [Tip|http://documentation.magnolia-cms.com/modules/forum.html#Headerdialog].
> Info and Tip look identical, should differentiate e.g. by making Info blue.
> * Icons:
> [Warning|http://documentation.magnolia-cms.com/modules/forum.html#Usage]
> * Lists:
> [Ordered|http://documentation.magnolia-cms.com/modules/forum.html#Createastylesheet]
> (procedure, numbered),
> [Unordered|http://documentation.magnolia-cms.com/modules/imaging.html#Features]
> (bulleted)
> h3. Documentation style guide
> [Documentation style guide on the
> wiki|http://wiki.magnolia-cms.com/display/DOCU/Documentation+Style+Guide]
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://jira.magnolia-cms.com/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
----------------------------------------------------------------
For list details see
http://www.magnolia-cms.com/community/mailing-lists.html
To unsubscribe, E-mail to: <[email protected]>
----------------------------------------------------------------
