[
http://jira.magnolia-cms.com/browse/DOCU-314?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Gavan Stockdale updated DOCU-314:
---------------------------------
Description:
Create a wiki or blog on the most effective way to document properties that
correspond to nodes (group, data etc). in AdminCentral functionality. To date
we have used tables and bullet lists to show when a property corresponds to a
node in, for example, the JCR Browser. The chief difficulty lies in maximising
available space in a single line of text.
The aim is to tease out a 'best practice' methodology for doing this across
docu etc. One that lets the reader intuitively grasp that what they see in a
page of documentation directly corresponds to what they see in AdminCentral.
Screen grabs certainly help, but it is not always possible to provide a screen
grab. Reasons being that docu team does not have every possible config in our
local instances or simply because the solution being described is ad hoc and
has been requested via the Community forum. As in, 'if you were to X, this is
how to configure Y".
To illustrate - In JCR browser, it is plausible to require a neatly documented
list of properties such as new page, new area, new component, new content node,
new data node. A simple list does provide sufficient information in regard to
the hierarchy:
* new page
* new area
* new component
* new content node
* new data node
Indents work for non tabular text. But then we need to add property
descriptions, value etc. Potentially tables are better for this, but tables
become messy when too much indenting occurs in the first row.
* new page
** new area
*** new component
**** new content node
***** new data node
Hence the dilemma.
was:
Create a wiki or blog on the most effective way to document properties that
correspond to nodes (group, data etc). in AdminCentral functionality. To date
we have used tables and bullet lists to show when a property corresponds to a
node in, for example, the JCR Browser. The chief difficulty lies in maximising
available space in a single line of text.
The aim is to tease out a 'best practice' methodology for doing this across
docu etc. One that lets the reader intuitive grasp that what they see in a page
of documentation directly corresponds to what they see in AdminCentral.
Screen grabs certainly help, but it is not always possible to provide a screen
grab. Reasons being that docu team does not have every possible config in our
local instances or simply because the solution being described is ad hoc and
has been requested via the Community forum. As in, 'if you were to X, this is
how to configure Y".
To illustrate - In JCR browser, it is plausible to require a neatly documented
list of properties such as new page, new area, new component, new content nod,
new data node. A simple list does provide sufficient information in regard to
the hierarchy:
* new page
* new area
* new component
* new content node
* new data node
Indents work for non tabular text. But then we need to add property
descriptions, value etc. Potentially tables are better for this, but tables
become messy when too much indenting occurs in the first row.
* new page
** new area
*** new component
**** new content node
***** new data node
Hence the dilemma.
> Create blog or wiki on how to document 'properties' in a visually intuitive
> way.
> ---------------------------------------------------------------------------------
>
> Key: DOCU-314
> URL: http://jira.magnolia-cms.com/browse/DOCU-314
> Project: Documentation
> Issue Type: Task
> Security Level: Public
> Reporter: Gavan Stockdale
> Assignee: Antti Hietala
>
> Create a wiki or blog on the most effective way to document properties that
> correspond to nodes (group, data etc). in AdminCentral functionality. To date
> we have used tables and bullet lists to show when a property corresponds to a
> node in, for example, the JCR Browser. The chief difficulty lies in
> maximising available space in a single line of text.
>
> The aim is to tease out a 'best practice' methodology for doing this across
> docu etc. One that lets the reader intuitively grasp that what they see in a
> page of documentation directly corresponds to what they see in AdminCentral.
> Screen grabs certainly help, but it is not always possible to provide a
> screen grab. Reasons being that docu team does not have every possible config
> in our local instances or simply because the solution being described is ad
> hoc and has been requested via the Community forum. As in, 'if you were to X,
> this is how to configure Y".
> To illustrate - In JCR browser, it is plausible to require a neatly
> documented list of properties such as new page, new area, new component, new
> content node, new data node. A simple list does provide sufficient
> information in regard to the hierarchy:
> * new page
> * new area
> * new component
> * new content node
> * new data node
> Indents work for non tabular text. But then we need to add property
> descriptions, value etc. Potentially tables are better for this, but tables
> become messy when too much indenting occurs in the first row.
> * new page
> ** new area
> *** new component
> **** new content node
> ***** new data node
> Hence the dilemma.
--
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
Alternatively, use our forums: http://forum.magnolia-cms.com/
To unsubscribe, E-mail to: <[email protected]>
----------------------------------------------------------------
