[mb-style] [Clean up CSG] Documentation

[Frederic Da Vitoria]

On Wed, Feb 13, 2008 at 7:20 AM, Brian Schweitzer <
brian.brianschweitzer at gmail.com> wrote:

> So I can start getting the new CSG documentation in order, so as to
> prepare for the eventual RFP, would everyone please take a look at the
> rewritten CSG I mentioned earlier,
> http://wiki.musicbrainz.org/BrianFreud/sandbox , *ignoring* content
> for the moment, only paying attention to the structure and style of
> the document?
>
> Brendon suggested, rather than continue to use the [part] style within
> structural examples that we currently use on the real CSG page, that
> we instead use colors.  See
> http://wiki.musicbrainz.org/BogdanButnaru/sandbox?highlight=%28sandbox%29
> for examples.  If there's feeling that this would be better, I can
> convert to using that style on the
> http://wiki.musicbrainz.org/BrianFreud/sandbox page.  If we could
> decide on this particular point by this weekend, this weekend I can do
> that conversion, if needed.  (Also, if we do use colors, opinions on
> which two colors are easiest to both read and identify as being
> separate colors against a white background?)


I think Brendon/Bogdan's color coding trick is nice, but it may trigger
issues if we try to use different text colors (Brendon's idea) AND different
background colors (as you already do for outlining the particular sub-part
you are speaking of). Maybe using bold to outline instead of color would be
better...

I think we should avoid blue since it is often used for links (my first
reaction at Bogdan's page was moving the mouse around to check if the blue
texts were links or not :-) ) And we should avoid red too because it has a
special meaning.

What about using background colors like you did, but for coding, and with
very light tones? This should
- avoid most color perception issues (since the contrast would still be
high),
- confusion with links,
- let us use text colors and bold for when we would need them.


Apart from that, is there anything else anyone thinks should be
> changed?  Is there something missing from the structure? (not the text
> - there's still text that needs to be written, mostly where
> indicated.)
>
> Also please look at it from the point of view of "If you, in an edit
> note, needed to indicate some specific part of the document to help
> identify why you did something or how someone else ought to do
> something per CSG, is the structure (5-II-b-example 3) sufficient, or
> are there areas that could use further indexing?


I don't see any, but I am quite sure we will find some as soon as we start
discussing the contents and we will of course say: "How could we have missed
this before?" :-D


-- 
Frederic Da Vitoria
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.musicbrainz.org/pipermail/musicbrainz-style/attachments/20080214/dd2d88c4/attachment-0001.htm