[
http://jira.magnolia-cms.com/browse/DOCUM-37?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Grégory Joseph updated DOCUM-37:
--------------------------------
Fix Version/s: 1.2
(was: 1.1)
Priority: Major (was: Critical)
> 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: Major
> Fix For: 1.2
>
>
> *(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]>
----------------------------------------------------------------
