[Bf-docboard] Being involved In documentation

[Nkansah Rexford]

Hello Chdancer,

I think you have a point, and its from a user who's got no idea what those
terms are.

However, look at it this way too. Trying to explain every single detail of
the steps will require another documentation on its own. "What repo is?",
"How to clone", "What is reST?", svn (what is even version control? duh!),
checkout (what am I buying?), pip, requirements.txt and so on.

Those are stuffs with detailed documentations on their own found everywhere
on the net. I don't think the getting started page on Blender should
aggregate all these information and present it to anyone who actually wants
to get started (beside's that'll be aggregating documentations into a
documentation).

Of course, more flesh can (and likely will) be added to those getting
started pages, but remember not *everything *can be covered or all the
terminologies can be expounded.

I think explaining every single thing on that page defeats the whole idea
of 'getting started'. Its not a training course. Its to get you started, so
they're pointers, offering guidance as to how to go about it.

Therefore, I think as someone who really wants to get started, doing a bit
more googling and reading outside the getting started page should make
things happen much easier, for both authors of get started pages and also
the 'get-startee' (bad english, but hope you get it)

I know its hard to understand pages like that, but I hope it gets improved
to the best possible to bridge the gap between devs and users.

rex

On Tuesday, January 13, 2015, Abuelo S. B. Chdancer <playadance at gmail.com>
wrote:

> Campbell Barton reminded...
>
> "While this is subjective, we have had contributions submitted via our
> project page:
>
> https://developer.blender.org/tag/documentation/ "
>
>
> Guys, someone who USES Blender may not know the first thing about coding,
> someone who can write simple prose explaining to another person in clear
> language how to DO something artistic may be totally useless when it comes
> to installing software or plugging in a USB plug.
>
> I bet a lot of possible contributors give up when they read this....
>
> "We have migrated the content over to reST format, so that the manual can
> be built with Sphinx. A good amount of work is still required to complete
> the migration (learn more about the open tasks in Phabricator).
>
> If you want to start contributing or want to have a look at the new
> manual, here we have some instructions.
> How to build the docs locally
>
>    - Checkout the Subversion repository svn checkout
>    https://svn.blender.org/svnroot/bf-manual/trunk
>    - Move to the location where the repo was cloned
>    - Run pip install -r requirements.txt (Windows user make sure you are
>    using Python 2.7, not 3.x)
>    - Build a section of the manual (for example make render)
>    - Launch the contents_quicky.html inside of the html folder and browse
>    the freshly build render docs
>
>
> That is a hundred times worse than trying to  use the wiki manual. It is
> mindboggingly offputting and not just incomprehensible but presents such a
> hurdle that most people will stop at that point and forget being involved.
>
> What it should say is.....
>
> Read this (hopefully well written and elegantly presented) webpage which
> explains how you register what you would like to do.
>
> If worried about 'no nothings' writing drivel, that is why we invented
> human editors. Also it is technically possible to have peer reviews of
> submitted entries prior to making the entry official.
>
> I was in the middle of working on my latest animation.....
>
>
>
>

-- 
+Rexford <http://google.com/+Nkansahrexford> | Africa Center
<http://africacenter.net> | WiR
<https://outreach.wikimedia.org/wiki/Wikipedian_in_Residence> | WikiAfrica
<http://wikiafrica.net> | User:Nkansahrexford
<http://en.wikipedia.org/wiki/User:Nkansahrexford>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20150113/2375bf1a/attachment.htm