[Bf-docboard] Documentation status and upgrade proposal

[koil .]

I like these idears and opinions how the manual should be, thanks for posting.

Koilz.

> Date: Wed, 7 May 2014 03:34:42 +1000
> From: ideasman42 at gmail.com
> To: bf-docboard at blender.org
> Subject: Re: [Bf-docboard] Documentation status and upgrade proposal
> 
> Hi, I wasn't aware of this list existing, but I was involved with the
> proposal to move the manual to a new system, will give some replies.
> 
> 
> 
> @brita
> 
> > Besides Manual, Dev and Tutorial also fit well in this scheme.
> 
> Not sure about this. Probably we can leave tutorials to other web
> sites (there are many), and Dev docs Im happy to keep on wiki for now.
> Since they fit the scheme of random-linked-pages, much better. (as in
> - they dont need to read so much like a book).
> 
> On the other hand, if this system works well, Im not totally against
> moving other parts of our wiki to it, But suggest to hold off until
> the manual has proven to be a success.
> 
> 
> 
> @Jeffrey H
> 
> Not sure what you mean about "linking" RestructuredText has a fairly
> nice method to add in cross-references and you can link to external
> sites too, I don't see this as an issue.
> 
> but agree "user contributions" is a concern. There is the idea that
> making user contributions `easy` is the best way to get a document
> done,
> 
> But IMHO the flip side of this --- is you get a lot of half edited
> pages, people start pages and dont finish them, and we get edits that
> probably should be reviewed or even rejected because of poor quality.
> Not to say editing documentation should be made difficult, just that
> the current wiki system has _not_ given us a really great manual IMHO
> (though parts of it are great of course).
> 
> Currently we have a situation where docs are *broken* and thats
> considered normal, I think with a better system authors can be in a
> bit more control and not just have random 2.4x pages mixed in with
> 2.5x, 2.6x, 2.7x docs.
> However at the end of this day this is still work someone has to do,
> our-millage-may-vary :)
> 
> Eventually I would like that the manual is a complete-document,
> covering areas of Blender in a clear & concise way, if something is
> incorrect or missing, this is reported as a bug/issue,
> it gets fixed before release, and we have some valuable resources we
> can include with Blender - basically manage this closer to how we
> manage Blender source code and releases.
> 
> Your last point about using a wiki to supplement is well taken, but I
> dont think its unique to wiki's --- the manual can link to any
> external resource when it makes sense to.
> 
> 
> 
> @marco ardito
> 
> re - contributions, right, users can prepare docs on a wiki, on
> github, anywhere... then submit for inclusion.
> Since this is just a directory of files we're not locked into one way
> of doing things.
> For the Python API docs, sometimes I've just got mails containing
> improvements, but Id like if we had something a bit nicer.
> 
> Expecting documentation authors to use git may be unrealistic, however
> github does have a way to edit text online and commit (without having
> to install git locally).
> 
> Note that we aren't locked into git, if we find some other system
> better for authors, we can move to that too.
> 
> 
> Your point about a manual not just being a reference is important,
> some wiki pages in our current manual - list every button in a panel
> with their tooltips,
> In most cases i dont think this really helps, its not giving insights
> into how things work or showing users why they might use certain
> features.
> 
> But I think this is orthogonal to which system is used, and am a bit
> worried if we try to migrate the manual to a new system at the same
> time as rewriting a lot, that it never gets finished.
> 
> 
> As for translations, while there is no special support for it (which
> could be nice to have), It could work out fine just to use branches,
> translators can review commits made since they last translated and
> update their versions if needed.
> 
> -- 
> - Campbell
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
 		 	   		  
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20140506/82587c7a/attachment.htm