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