<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'>> Hi there,<br>> Recently we've been adding some notes to the 'writing style',<br>><br>> Currently its mainly a list of what *not* to do (based on reading the<br>> lower quality wiki-manual text).<br>><br>> See:<br>> https://developer.blender.org/diffusion/BM/browse/master/readme.rst$34<br>><br>> But I'd be interested to get feedback from people on this list who<br>> have experience technial writing.<br>><br>> --<br>> - Campbell<br><br>I think this is the same link.<br>https://www.blender.org/manual/about/style_guide.html#writing-style<br><br>I didnt see this before, I guess the link changed or something.<br>These writing style notes, are very useful for writers.<br><br>I would propose some more but I havnt wrote much for a while.<br>These are some things I was unsure about.<br><br>1: How to write workflows. i.e.<br>Dont turn it into a big tutorial.<br>Have clear small steps, the user can follow.<br>Only write workflows for common often used tasks, not specific things most users probably wont do.<br><br>2: How to write reference for a tools/operators, and where and how they should be documented.<br>I know each editor has a big set of tools, sometimes its best to restructure a page, or add sub pages for categories of tools.<br>I think the modeling section does this well.<br>https://www.blender.org/manual/modeling/index.html<br><br>3: How to write reference for a panel of tools i.e.<br>How to structure the page for the panel of tools, different modes etcetera.<br>How to reference different parts of an image of a panel.<br><br>4: How tools should be categories.<br>I guess this depends on the editor and what types of tools/operators exist.<br><br>5: I find documented blend file examples useful in some cases, like when its complicated to set something up, or describe what something does in words.<br>Though I was never sure if it was ok to add documented examples.<br>Also documented blend file examples help to explain how features and settings works sometimes.<br><br>6: How to structure different types of pages.<br><br>I dunno, this is just my opinion, its up to blender devs whats correct/acceptable.<br>Above is just a draft some writing style ideas.<br><br>koilz </div></body>
</html>