Changes to our style process (Important)

classic Classic list List threaded Threaded
22 messages Options
12
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Changes to our style process (Important)

Nicolás Tamargo de Eguren
Hi! So, this has already been posted to the blog, but for those here who don't read the blog, I'll repost:

At the MusicBrainz Summit last month in Copenhagen, one of the topics to
be discussed was the state of the style guidelines and style process.
One thing those present agreed on was that the process was in need of
reform, for several reasons: the complexity of the process,
inconsistency with other processes in the project, the high level of
individual commitment required to make changes, long-running discussions
without conclusion or followthrough, and ultimately the state of the
final product, the style guidelines themselves. The inaccessibility of
our existing process meant that many users, both new and old, avoided
the style process, and this hurts the project: style is part of what
makes MusicBrainz what it is, and low participation means our guidelines
have grown both internally inconsistent and out of sync with community
practice. Nor is the style process a new problem for MusicBrainz:
historically, it’s changed several times and some past style leaders
have vanished into thin air.  After all, it is a hard job, for a
volunteer, to convince many voices to come to a consensus.

To improve upon these issues, we’ve decided to make two major changes.

First: to designate our JIRA issue tracker at tickets.musicbrainz.org as
the central coordination point for style issues. This way, any issue, be
it style-related or code-related, is reported and discussed in the same
place (and should an issue be misfiled, it’s easily corrected). The
issue tracker can also collect links to other discussions, in edit
notes, the forums, IRC, etc., and store links to related issues such as
features in need of implementation.

Second: to promote our current Style Leader to Style Benevolent Dictator
For Life (Style BDFL). Nicolás Tamargo (reosarevok) will then be in
charge of considering tickets and implementing changes in the style
guidelines. This change shifts the burden of evaluating style issues
from the community to our newly appointed BDFL. For simple changes and
for simple improvements to consistency and writing style, the BDFL can
change things directly, without need for lengthy discussion. Of course,
his work won’t happen in a vacuum: for changes that are complex or
contentious, the role of the BDFL will be to gather feedback and
determine the next steps before making changes. To this end, he may
occasionally call for a non-binding vote on a particular topic, to
collect a snapshot of community opinion to augment existing discussion,
all in order to make a better informed decision.

We hope that this new process will make contribution to the creation of
style guidelines easier and less onerous a commitment for everyone, and
that the resulting style guidelines will be more up-to-date, more
consistent, and more clearly written and organized. To test it out,
we’re going to try this process for 6 months, and then review how things
have progressed and if the process needs further tweaking or even
complete replacement.

tl;dr: Style system has changed, new info at http://musicbrainz.org/doc/Proposals

_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

lixobix
Nicolás Tamargo de Eguren wrote
Hi! So, this has already been posted to the blog, but for those here who
don't read the blog, I'll repost:

At the MusicBrainz Summit last month in Copenhagen, one of the topics to
be discussed was the state of the style guidelines and style process.
One thing those present agreed on was that the process was in need of
reform, for several reasons: the complexity of the process,
inconsistency with other processes in the project, the high level of
individual commitment required to make changes, long-running discussions
without conclusion or followthrough, and ultimately the state of the
final product, the style guidelines themselves. The inaccessibility of
our existing process meant that many users, both new and old, avoided
the style process, and this hurts the project: style is part of what
makes MusicBrainz what it is, and low participation means our guidelines
have grown both internally inconsistent and out of sync with community
practice. Nor is the style process a new problem for MusicBrainz:
historically, it’s changed several times and some past style leaders
have vanished into thin air.  After all, it is a hard job, for a
volunteer, to convince many voices to come to a consensus.

To improve upon these issues, we’ve decided to make two major changes.

First: to designate our JIRA issue tracker at tickets.musicbrainz.org as
the central coordination point for style issues. This way, any issue, be
it style-related or code-related, is reported and discussed in the same
place (and should an issue be misfiled, it’s easily corrected). The
issue tracker can also collect links to other discussions, in edit
notes, the forums, IRC, etc., and store links to related issues such as
features in need of implementation.

Second: to promote our current Style Leader to Style Benevolent Dictator
For Life (Style BDFL). Nicolás Tamargo (reosarevok) will then be in
charge of considering tickets and implementing changes in the style
guidelines. This change shifts the burden of evaluating style issues
from the community to our newly appointed BDFL. For simple changes and
for simple improvements to consistency and writing style, the BDFL can
change things directly, without need for lengthy discussion. Of course,
his work won’t happen in a vacuum: for changes that are complex or
contentious, the role of the BDFL will be to gather feedback and
determine the next steps before making changes. To this end, he may
occasionally call for a non-binding vote on a particular topic, to
collect a snapshot of community opinion to augment existing discussion,
all in order to make a better informed decision.

We hope that this new process will make contribution to the creation of
style guidelines easier and less onerous a commitment for everyone, and
that the resulting style guidelines will be more up-to-date, more
consistent, and more clearly written and organized. To test it out,
we’re going to try this process for 6 months, and then review how things
have progressed and if the process needs further tweaking or even
complete replacement.

tl;dr: Style system has changed, new info at
http://musicbrainz.org/doc/Proposals

_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Seem like some good changes. Lets see how it goes.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

David Gasaway
In reply to this post by Nicolás Tamargo de Eguren
On Sun, Oct 19, 2014 at 10:42 AM, Nicolás Tamargo de Eguren
<[hidden email]> wrote:

> tl;dr: Style system has changed, new info at
> http://musicbrainz.org/doc/Proposals

Hi.  How should an editor keep abreast of style changes under the new system?

--
-:-:- David K. Gasaway
-:-:- Email: [hidden email]

_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

Nicolás Tamargo de Eguren
On Thu, Oct 23, 2014 at 1:25 AM, David Gasaway <[hidden email]> wrote:
On Sun, Oct 19, 2014 at 10:42 AM, Nicolás Tamargo de Eguren
<[hidden email]> wrote:

> tl;dr: Style system has changed, new info at
> http://musicbrainz.org/doc/Proposals

Hi.  How should an editor keep abreast of style changes under the new system?

For checking what changes have happened, we'll be posting on the blog (category "Style") a list of implemented changes every two weeks (more or less). For discussion and feedback before things are implemented, for now I plan to post both here and on the Style section of the forum, so being here should be enough :)

_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

lixobix
Nicolás Tamargo de Eguren wrote
On Thu, Oct 23, 2014 at 1:25 AM, David Gasaway <[hidden email]> wrote:

> On Sun, Oct 19, 2014 at 10:42 AM, Nicolás Tamargo de Eguren
> <[hidden email]> wrote:
>
> > tl;dr: Style system has changed, new info at
> > http://musicbrainz.org/doc/Proposals
>
> Hi.  How should an editor keep abreast of style changes under the new
> system?
>

For checking what changes have happened, we'll be posting on the blog
(category "Style") a list of implemented changes every two weeks (more or
less). For discussion and feedback before things are implemented, for now I
plan to post both here and on the Style section of the forum, so being here
should be enough :)

_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Is there a way to get email updates when the blog is updated?
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

Robert Bihlmeyer
On 2014-10-23 16:34 lixobix wrote:
> Is there a way to get email updates when the blog is updated?
I don't think so. But http://blog.musicbrainz.org/feed/ is an RSS feed,
that most popular mail user agents know how to handle. There are also
phone apps for twitchers.

See https://en.wikipedia.org/wiki/Comparison_of_feed_aggregators for an
overview.

--
Robbe


_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

Robert Bihlmeyer
In reply to this post by Nicolás Tamargo de Eguren
On 2014-10-23 00:30, Nicolás Tamargo de Eguren wrote:
> For checking what changes have happened, we'll be posting on the blog
> (category "Style") a list of implemented changes every two weeks (more or
> less).
Can we get versioned (or time stamped) style documents?

That would make it possible to look up
style-as-was-fashionable-when-this-edit-was-made. It is sometimes useful
to determine why an edit was done the way it was.

--
Robbe


_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

Rachel Dwight

On Oct 23, 2014, at 3:08 PM, Robert Bihlmeyer <[hidden email]> wrote:

> On 2014-10-23 00:30, Nicolás Tamargo de Eguren wrote:
>> For checking what changes have happened, we'll be posting on the blog
>> (category "Style") a list of implemented changes every two weeks (more or
>> less).
> Can we get versioned (or time stamped) style documents?
>
> That would make it possible to look up
> style-as-was-fashionable-when-this-edit-was-made. It is sometimes useful
> to determine why an edit was done the way it was.

I second this. A lot of our guidelines haven’t been updated in years (many predate NGS).

>
> --
> Robbe
>
>
> _______________________________________________
> MusicBrainz-style mailing list
> [hidden email]
> http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style


_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

Frederic Da Vitoria
In reply to this post by Robert Bihlmeyer
2014-10-23 22:08 GMT+02:00 Robert Bihlmeyer <[hidden email]>:
On 2014-10-23 00:30, Nicolás Tamargo de Eguren wrote:
> For checking what changes have happened, we'll be posting on the blog
> (category "Style") a list of implemented changes every two weeks (more or
> less).
Can we get versioned (or time stamped) style documents?

That would make it possible to look up
style-as-was-fashionable-when-this-edit-was-made. It is sometimes useful
to determine why an edit was done the way it was.

Am I missing something or wouldn't the wiki history answer this need?

--
Frederic Da Vitoria
(davitof)

Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org

_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

Robert Bihlmeyer
Am 2014-10-23 22:27, schrieb Frederic Da Vitoria:
> 2014-10-23 22:08 GMT+02:00 Robert Bihlmeyer <[hidden email]>:
>
>> Can we get versioned (or time stamped) style documents?
> Am I missing something or wouldn't the wiki history answer this need?
Style is currently split into more than 30 wiki pages. That's fine if
you're reading the current version. But AFAIK MediaWiki does not offer
the possibility to look at multiple pages in their
January-1st-2012-version -- only for one page at a time.

So while possible in principle, it's very cumbersome to get at the whole
style guide in its January-1st-2012-incarnation.

--
Robbe


_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

Calvin Walton-2
On Sun, 2014-10-26 at 23:00 +0100, Robert Bihlmeyer wrote:

> Am 2014-10-23 22:27, schrieb Frederic Da Vitoria:
> > 2014-10-23 22:08 GMT+02:00 Robert Bihlmeyer <[hidden email]>:
> >
> > > Can we get versioned (or time stamped) style documents?
> > Am I missing something or wouldn't the wiki history answer this
> > need?
> Style is currently split into more than 30 wiki pages. That's fine if
> you're reading the current version. But AFAIK MediaWiki does not
> offer
> the possibility to look at multiple pages in their
> January-1st-2012-version -- only for one page at a time.
>
> So while possible in principle, it's very cumbersome to get at the
> whole
> style guide in its January-1st-2012-incarnation.

With the changes in how we're doing the style process, I wonder if it
might make more sense to change the process for editing the style
guide to make it more like code or documentation than a wiki.

There are various ways of having documents done in a git repository,
all versioned together, and then generating static html pages from a
specific version to be published: e.g. what you see with
https://readthedocs.org/

Just a thought, but it would enable easier tracking of changes, and
allow generating docs from a specific date or version of the style
guide if desired.


--
Calvin Walton <[hidden email]>

_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

LordSputnik

I very much agree with this. While having only one person editing docs may be a good idea for ensuring consistency and quality, it also rules out the main advantage of storing docs in a wiki.

It'd probably simplify things if all the docs were written in Markdown or RST, then displayed as static pages on the site, as Calvin suggested.


_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

Ian McEwen
In reply to this post by Calvin Walton-2
On Wed, Oct 29, 2014 at 12:14:39PM -0400, Calvin Walton wrote:

> On Sun, 2014-10-26 at 23:00 +0100, Robert Bihlmeyer wrote:
> > Am 2014-10-23 22:27, schrieb Frederic Da Vitoria:
> > > 2014-10-23 22:08 GMT+02:00 Robert Bihlmeyer <[hidden email]>:
> > >
> > > > Can we get versioned (or time stamped) style documents?
> > > Am I missing something or wouldn't the wiki history answer this
> > > need?
> > Style is currently split into more than 30 wiki pages. That's fine if
> > you're reading the current version. But AFAIK MediaWiki does not
> > offer
> > the possibility to look at multiple pages in their
> > January-1st-2012-version -- only for one page at a time.
> >
> > So while possible in principle, it's very cumbersome to get at the
> > whole
> > style guide in its January-1st-2012-incarnation.
>
> With the changes in how we're doing the style process, I wonder if it
> might make more sense to change the process for editing the style
> guide to make it more like code or documentation than a wiki.
>
> There are various ways of having documents done in a git repository,
> all versioned together, and then generating static html pages from a
> specific version to be published: e.g. what you see with
> https://readthedocs.org/
>
> Just a thought, but it would enable easier tracking of changes, and
> allow generating docs from a specific date or version of the style
> guide if desired.
>
This was, in fact, part of the hidden goal here :) As those of you who
were at the summit know, my original proposal didn't centralize things
quite as far as what ended up being decided, but even without that it
moved writing it to people who are certainly able to use
developer-oriented tools like git.

I think that at present between the upcoming schema change,
acousticbrainz, the holidays, and the various other work I and the other
devs have been doing, right now the style changes will focus on
clarifying writing style and dealing with neglected things. But
hopefully soon.

P.S. the usual tool for this in perl is POD:
http://perldoc.perl.org/perlpod.html /
http://perldoc.perl.org/pod2html.html -- example output at e.g.
https://metacpan.org/pod/Catalyst (and the rest of metacpan)

>
> --
> Calvin Walton <[hidden email]>
>
> _______________________________________________
> MusicBrainz-style mailing list
> [hidden email]
> http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style

_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style

attachment0 (188 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

tommycrock

Out of interest, does this mean we're getting rid of the distinction between official style guidelines and docs? Or are docs still open to community editing?


_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

Ian McEwen
On Wed, Oct 29, 2014 at 10:55:53PM +0000, Tom Crocker wrote:
> Out of interest, does this mean we're getting rid of the distinction
> between official style guidelines and docs? Or are docs still open to
> community editing?

Any moving things into the codebase doesn't change the 'community
editing' aspect, just the technical process and prerequisites for
implementing changes and the particular gatekeepers involved in changes
appearing on the site -- instead of editing a wiki and transclusion
editors, template files or other code and those with merge power plus
the schedule of the beta/production merge process.

It's similar to the style change: instead of a proposal system with wiki
pages and a gatekeeper embedded in the patience to negotiate the old
style process, community participation goes through interaction with
reosarevok, who serves as the gatekeeper himself.

Or, in short, anyone can open pull requests:
https://bitbucket.org/metabrainz/musicbrainz-server

P.S. for the curious what template files look like (which would probably
be where documentation of this sort ends up):
https://github.com/metabrainz/musicbrainz-server/tree/master/root has
them all. (github for this link because it has better display for this
sort of file; it and bitbucket are kept in sync)

_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style

attachment0 (188 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

Paul Taylor-3
On 29/10/2014 23:24, Ian McEwen wrote:

> On Wed, Oct 29, 2014 at 10:55:53PM +0000, Tom Crocker wrote:
>> Out of interest, does this mean we're getting rid of the distinction
>> between official style guidelines and docs? Or are docs still open to
>> community editing?
> Any moving things into the codebase doesn't change the 'community
> editing' aspect, just the technical process and prerequisites for
> implementing changes and the particular gatekeepers involved in changes
> appearing on the site -- instead of editing a wiki and transclusion
> editors, template files or other code and those with merge power plus
> the schedule of the beta/production merge process.
>
> It's similar to the style change: instead of a proposal system with wiki
> pages and a gatekeeper embedded in the patience to negotiate the old
> style process, community participation goes through interaction with
> reosarevok, who serves as the gatekeeper himself.
>
> Or, in short, anyone can open pull requests:
> https://bitbucket.org/metabrainz/musicbrainz-server
>
> P.S. for the curious what template files look like (which would probably
> be where documentation of this sort ends up):
> https://github.com/metabrainz/musicbrainz-server/tree/master/root has
> them all. (github for this link because it has better display for this
> sort of file; it and bitbucket are kept in sync)
>
I disagree, although one person is currently has now been put  in charge
of the style process this is a new change that may need tweaking, and
future tweaking may involve delegating some of the style modifications
so we should not assume that only one person will always be making all
the edits. Nor we should assume that future editors will be git literate
or similar, this puts unneccessary restrictions on possible contributors
, surely one of the main point of the style guidelines has been they can
be contributed to my non-coders/tech.

Also wouldnt this mean that unlike a wiki  if we did move to the process
your are advocating you wouldnt be able to see how changes made looked
on the site before comitting without having a musicbrainz server setup.
Actually to me this points to a fundamental problem in Musicbrainz,
again and again assumptions are made all Musicbrainz contributors are
coders whose preferred OS is Linux , this isnt true, but assuming it is
true discourages contributions from the those not fitting into this niche

ijabz

_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

Nicolás Tamargo de Eguren
On Thu, Oct 30, 2014 at 3:11 PM, Paul Taylor <[hidden email]> wrote:
I disagree, although one person is currently has now been put  in charge
of the style process this is a new change that may need tweaking, and
future tweaking may involve delegating some of the style modifications
so we should not assume that only one person will always be making all
the edits. Nor we should assume that future editors will be git literate

Both bitbucket and github allow on-site editing of files that does most of the branching and pull-requesting in the background. So it's not exactly much more complicated than editing a wiki, and it doesn't require basically any amount of actual git-literacy. Yes, it lacks being able to preview, but that shouldn't matter much - after all, right now you can preview how stuff looks in the wiki but not in /doc/, anyway.
 
this puts unneccessary restrictions on possible contributors
, surely one of the main point of the style guidelines has been they can
be contributed to my non-coders/tech.

That changes how? To be able to write a wiki page you need a starting template and/or knowledge of wiki syntax. To be able to write a static TT template you need a starting template and/or knowledge of basic html syntax. Both are similarly simple. In fact, with our old wiki templates for relationships, for example, using them was probably *quite a bit harder* than using TT would be (mostly because they were a badly written mess of a template, but people managed anyway). Plus, people can always put together a plain text draft on the ticket, to be made into a doc template by the person implementing it.
 
Also wouldnt this mean that unlike a wiki  if we did move to the process
your are advocating you wouldnt be able to see how changes made looked
on the site before comitting without having a musicbrainz server setup.

Yes, this is the only drawback, but as mentioned previously, it seems minor enough. The people writing the final docs should have the (fairly basic) knowledge to know what to expect, and also probably their own server setup anyway.
 
Actually to me this points to a fundamental problem in Musicbrainz,
again and again assumptions are made all Musicbrainz contributors are
coders whose preferred OS is Linux , this isnt true, but assuming it is
true discourages contributions from the those not fitting into this niche

How is this assumption made here? The whole point of this is allowing *everyone* to contribute, regardless of their coding expertise, by having someone who can take care of the more code-y stuff (instead of having non-coders fight confusing mediawiki templates). Actually, I don't see where that assumption is made *anywhere* in the project, to be honest, as a part-time coder (and non-coder when I started) whose usual OS is Win 8. But even if it was true elsewhere, I really don't see it here.

_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

Paul Taylor-3
On 30/10/2014 13:54, Nicolás Tamargo de Eguren wrote:
On Thu, Oct 30, 2014 at 3:11 PM, Paul Taylor <[hidden email]> wrote:
I disagree, although one person is currently has now been put  in charge
of the style process this is a new change that may need tweaking, and
future tweaking may involve delegating some of the style modifications
so we should not assume that only one person will always be making all
the edits. Nor we should assume that future editors will be git literate

Both bitbucket and github allow on-site editing of files that does most of the branching and pull-requesting in the background. So it's not exactly much more complicated than editing a wiki, and it doesn't require basically any amount of actual git-literacy. Yes, it lacks being able to preview, but that shouldn't matter much - after all, right now you can preview how stuff looks in the wiki but not in /doc/, anyway.
But /wiki and /doc are VERY similar whereas i assume without the templates there will be quite a difference in what they look like. To my mind introducing Git and Templates and lumping more files into the already Monolithic codebase is not a good idea and is certainly this is not making things simpler, I don't think this is the direction that other sites are going and I'm now wondering if there are any other 'hidden goals' with this idea 
 
this puts unneccessary restrictions on possible contributors
, surely one of the main point of the style guidelines has been they can
be contributed to my non-coders/tech.

That changes how? To be able to write a wiki page you need a starting template and/or knowledge of wiki syntax. To be able to write a static TT template you need a starting template and/or knowledge of basic html syntax.
The difference is the kind of users that are used to writing wikis are a bit different to those who write pure html and wikis protect users from making invalid modifications. Consider Wikipedia do you think that site would work better if users had to create valid html pages rather than edit in the wiki style.

Also wouldnt this mean that unlike a wiki  if we did move to the process
your are advocating you wouldnt be able to see how changes made looked
on the site before comitting without having a musicbrainz server setup.

Yes, this is the only drawback, but as mentioned previously, it seems minor enough. The people writing the final docs should have the (fairly basic) knowledge to know what to expect, and also probably their own server setup anyway.
 
Its one drawback, but what are the actual advantages I don't see them, we shoudn't be adding any drawbacks.
Actually to me this points to a fundamental problem in Musicbrainz,
again and again assumptions are made all Musicbrainz contributors are
coders whose preferred OS is Linux , this isnt true, but assuming it is
true discourages contributions from the those not fitting into this niche

How is this assumption made here? The whole point of this is allowing *everyone* to contribute, regardless of their coding expertise, by having someone who can take care of the more code-y stuff (instead of having non-coders fight confusing mediawiki templates). Actually, I don't see where that assumption is made *anywhere* in the project, to be honest, as a part-time coder (and non-coder when I started) whose usual OS is Win 8. But even if it was true elsewhere, I really don't see it here.
Well look at what you just wrote above 'and also probably their own server setup anyway' you have made the assumption yourself.

To be clear I'm not against you being the final decision maker and only editor for the time being, but we need to try test out the new process before making changes like these, and  what I'm against is making changes to the way things works so that in the future it will be harder for others to edit if decide want to spread the role. And putting a dependency that the final editor has to have their own server running just for modifying and viewing the changes is not a good thing, and what happens if you get hit by a bus and we need a new style editor, Ian put himself and nikki forward in the original proposal but I really don't think having the main Musicbrainz developer involved (whoever they are) is a good idea at all.

1. Developers have there plate full already
2. There is a conflict of interest between making the style  proposals and being the implementor
3. Concentrates control to fewer people, leaving musicbrainz exposed
4. Developers notorious for being bad at documentation

Maybe Im the only one thinking like this, and its not the most pressing issue for me so I wont go on about it any further, but the absense of discussion at the musicbrainz summit makes me feel I have a duty to put alternative povs over.

ijabz

_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

LordSputnik

Yeah, I have to agree with Paul, making documentation editors edit HTML templates is an unnecessary complication, when there are plenty of existing plain text to HTML conversion systems which would work just as well.

AFAIK our current system doesn't require any data from the rest of the server, so what advantage does using TT provide? I'm also against any further integration of the documentation system into the MBS codebase.

I do still think that putting it all on Git is a good idea though (especially given the online editing capabilities of GH and BB). Just not TT templates, and separate from the server code.


_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Changes to our style process (Important)

Alexander VanValin
On 10/30/2014 05:58 PM, Ben Ockmore wrote:

> I do still think that putting it all on Git is a good idea though
> (especially given the online editing capabilities of GH and BB). Just
> not TT templates, and separate from the server code.
>

For anybody interested, keep an eye on
https://github.com/PharkMillups/beautiful-docs , an ever-growing roundup
of doc-related resources.


_______________________________________________
MusicBrainz-style mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-style
12
Loading...