[Bf-docboard] Feedback on Writing Style

[koil .]

> Hi there,
> Recently we've been adding some notes to the 'writing style',
>
> Currently its mainly a list of what *not* to do (based on reading the
> lower quality wiki-manual text).
>
> See:
> https://developer.blender.org/diffusion/BM/browse/master/readme.rst$34
>
> But I'd be interested to get feedback from people on this list who
> have experience technial writing.
>
> --
> - Campbell

I think this is the same link.
https://www.blender.org/manual/about/style_guide.html#writing-style

I didnt see this before, I guess the link changed or something.
These writing style notes, are very useful for writers.

I would propose some more but I havnt wrote much for a while.
These are some things I was unsure about.

1: How to write workflows. i.e.
Dont turn it into a big tutorial.
Have clear small steps, the user can follow.
Only write workflows for common often used tasks, not specific things most users probably wont do.

2: How to write reference for a tools/operators, and where and how they should be documented.
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.
I think the modeling section does this well.
https://www.blender.org/manual/modeling/index.html

3: How to write reference for a panel of tools i.e.
How to structure the page for the panel of tools, different modes etcetera.
How to reference different parts of an image of a panel.

4: How tools should be categories.
I guess this depends on the editor and what types of tools/operators exist.

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.
Though I was never sure if it was ok to add documented examples.
Also documented blend file examples help to explain how features and settings works sometimes.

6: How to structure different types of pages.

I dunno, this is just my opinion, its up to blender devs whats correct/acceptable.
Above is just a draft some writing style ideas.

koilz 		 	   		  
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20150116/a4ba673f/attachment.htm