[Bf-docboard] Documentation status and upgrade proposal

[Campbell Barton]

On Wed, May 7, 2014 at 8:34 AM, Noel Stoutenburg <brasshat at core.com> wrote:
> koil:
>
> I've reviewed the ideas posted on this topic, and given the matter a
> good deal of thought. My reaction is mixed. In theory, I woudn't have
> any problem with porting the User Manual for Blender to the Sphinx
> platform, (or some other one, if it be deemed reasonable and proper to
> do so). However, since Blender is open source, and community developed,
> I think it that it is imperative that there be mechanism for maintaining
> user development of the documentation, too. And, unless I totally
> misunderstand the new platform (and that's not an outlandish
> possibility),

Nope, sounds like you understand whats being proposed.

> moving the whole manual to the proposed new platform is
> going to reduce the contributions to the documentation by members of the
> community by a couple of orders of magnitude, and unless there is a
> sizeable cohort of documentation waiting in the wings, I'm loathe to
> disenfranchise a significant number of contributors to the documentation.

I'm not so certain of this, Probably we loose some drive-by contributors,
Its all speculation at this point, but Im not convinced being overly
relaxed about anyone having access to the wiki really results in great
docs.

I find it hard to articulate, but having a higher barrier of entry (in
terms of quality), can be an incentive and make people more invested
in a project.

At the moment someone adds a page, forgets about it, its deleted
sometime later... nobody really cares a lot.

Compare this to people submitting patches to Blender's code - they
might go through 2-10 review iterations until its really good quality.
Getting this kind of review & validation from others can be motivating
too, especially if you feel your contributing to something thats high
quality.
And they very much care if their code is kicked out later on!

Not sure we can foster exactly this process for docs.

All that said - The proposal is a risk, maybe it fails if we do a poor
job or put in place some system which is too hard to use, or maybe we
just need to better manage the existing wiki manual.

> I would therefore propose that the WIKI should be treated as a
> development place, or, to use a literary metaphor, the "first couple of
> drafts" where the various parts of the documentation are, fleshed out
> and brought to a certain editorial standard. When the pages have reached
> that point, they could then be ported to the final cut version, and
> ported to the new platform.

Sure, anyone proposing a new chapter can get it ready externally and
propose it for inclusion. (Wiki is fine).

We could support contributions via pull requests on github/bitbucket,
with docs for exactly how this works for anyone not familiar with
these services.
- Just to say we can still have online editing if we want, though it
wouldn't be the same as a wiki.

> If the new proposal breaks, or makes it significantly harder for users
> to contribute to the knowledge base, I'm opposed. If the new platform
> can be implemented in a way which the ability of users to contribute
> persists, I stand in favor.
>
> Noel Stoutenburg.
> Sometime WIKI contributor, under the username "brasshat".
>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard



-- 
- Campbell