[Bf-docboard] Documentation status and upgrade proposal

[marco ardito]

Il 06/05/2014 17:48, Jeffrey H ha scritto:
> I agree with this change. My main concerns are about linking and user 
> contributions. To clarify, we are keeping the wiki? If the new manual 
> format is automated, how easily could other users add/edit 
> information, or would this be allowed only on the wiki? Regarding 
> linking: How will it handle referencing other features or attributes 
> that relate to the topic in question? Ex: "For more information, see 
> ..." How would this relate to the wiki? Perhaps something along the 
> lines of "For user documentation, see the wiki page: %" could bridge 
> the two.
>
> My point is that official documentation is often not enough to 
> describe a use for a feature (technicality is generally all that is 
> given), so a wiki is an extremely useful supplement.
I Agree. User participation should be encouraged, but also monitored: 
keeping a well shaped, versioned manual is not a job for everyone (with 
mediawiki, sphinx-doc or else). Or, it should be done by a dedicated, 
trained team. Perhaps volunteers could prepare a new/revised chapter in 
the wiki, and when it is well shaped, and approved, someone else moves 
it to sphinx-doc (with due credits, probably). But it sounds some 
doubled work...

Sometimes I thought also that a "manual" should not necessarily be "a 
reference".
A manual should  perhaps "train" about "3d topics" with theory, examples 
and ALSO a reference, which could be perhaps be a separated think, 
linked, aimed to describe more the application used (UI, etc) than the 
concept itself.
And the same "topics training" manual could link the reference of more 
than one version, if available.
Maybe.

It would be also nice to find the best method to encourage translations, 
and keeping them updated, because so many people is kept behind by the 
english barrier (I know that learning english should be chapter 0 of the 
Blender manual, but...), btw, the website also could need 
translations... just like gooseberry/cloud sites... :D

Marco

PS: I read <<after some conversations about how to improve Blender's 
documentation system>>... where did those conversations happen? IRC? I 
would have liked to join such conversations...



-------------------
[Ai sensi e per  gli  effetti della Legge sulla tutela della privacy
(L. 196/2003), questa  mail  è destinata unicamente alle persone sopra
indicate e le informazioni in essa contenute sono da considerarsi
strettamente riservate. E' proibito leggere, copiare, usare o
diffondere il contenuto della presente mail senza autorizzazione.
Se avete ricevuto questo messaggio per errore, siete pregati di
rispedire la stessa al mittente. Grazie]