Meta:BR/Wiki Tasks/Manual

From BlenderWiki

Other pages about editing the wiki:

Todos list

Writer Guide | Style Guide | Notes for translators

---

When Blender.Org announces a first Release Candidate (RC1) for a new version, the User Manual update process needs to start. The goal of the process is to comprehensively update the entire User Manual (Manual/xxx) for any and all updates to existing functionality, new features and enhancements, and UI changes that will be in the new release, in all languages.

[edit] Process

The first step is to create a “Wiki Tasks/ManualVXX” (See #Template_for_Wiki_Tasks.2FManualVXX) page, where VXX is the version and release number, such as 243 for Blender version 2.43. The contents of this page should be an edited copy of the current Table of Contents for each language, starting with English. The edits include Level 1 heading for each language, preserving indentation for readability, starting each line with the

to do

 update needed?

template, removing any column breaks and formatting, removing links to tutorials, and the addition of any new features that will show up in the TOC. The editor/author should check the Release Notes as a starting point for this list of new topics in the TOC.

Next, each author interested in contributing to the new release has to check the manual, compare it to the new functionality, and determine whether or not the section really needs to be updated. The release notes page has to annotate what sections need updating and to what degree, and allow an author to volunteer to take on the task, with some coordination so that we aren’t tripping on each other’s toes.

For all parts of the manual NOT affected by the release, the author/editor should assign an

on hold

 no changes? authorname

completion status template to the line, indicating that they don’t think anything needs to be done. An editor or independent author/contributor interested in that section must verify that it is unaffected, and, if so, assign a

done

 authorname editorname (no changes)

status to the topic.

When an author commits to updating the section, they change the To Do status to

in progress 25%

 authorname

where authorname is their wiki logon name. VOLUNTEERING OTHER AUTHORS IS PROHIBITED. As they work, the author should update the progress percentage number accordingly. Depending on the number you put in, the progressbar will change in steps of 25%: so 0%, 25%, 50%, 75%, 100%. Numbers below the zero and over the 100 will give 0 anyway.

When the author gets to 100% complete, an independent editor needs to review their work for accuracy, 1st person tense, completeness, non-technical language, etc. Any major edits required will be communicated back through the author’s talk page for the author to complete. Minor edits will be made on the spot, and, if the page is good enough, a

done

 authorname, editorname (summary)

status is assigned, where summary is a very brief (40 character) summary of what was done, or just a link to the actual release note section that caused the update.

This way, when updates are in progress, it is very easy to see who is working on what and how far along the update project is. When complete, a complete changelog is readily observed to see who contributed their time and energy to make the manual the very best it can be.

[edit] Templates

Usable templates I’ve found so far (see also User:JesterKing#Mediawiki_projects)

• <nowiki>
  to do
   item</nowiki> gives
  **
  to do
   item
  *<nowiki>
  on hold
   uncertain project</nowiki> gives
  **
  on hold
   uncertain project
  *<nowiki>
  done
   good project</nowiki> gives
  **
  done
   good project
  *<nowiki>
  in progress 0%
   going to todo this page...</nowiki> gives
  **
  in progress 0%
   going to todo this page...
  *<nowiki>
  in progress 10%
   just started, made 10%</nowiki> gives
  **
  in progress 10%
   just started, made 10%
  *<nowiki>
  in progress 30%
   good progresses, 30%</nowiki> gives
  **
  in progress 30%
   good progresses, 30%
  *<nowiki>
  in progress 65%
   going on well, 65%</nowiki> gives
  **
  in progress 65%
   going on well, 65%
  *<nowiki>
  in progress 90%
   almost finished, 90%!</nowiki> gives
  **
  in progress 90%
   almost finished, or even finished! 90%!

[edit] Images

Outdated images should be replaced with new ones. Please read Template:Updateimage on how this should be done.

If you stumble upon an image that you either can’t replace for whatever reason please at least mark it with <tt><nowiki></nowiki></tt>.

A list of images marked as such is here: Category:Update image

[edit] Completeness

How do you know when you have completed updates for a section, and what should you check and do in order to update a section of the user manual? Here is your checklist:

1. Download and install the RC1. Do not assume something works some way; actually use it in order to give first-hand knowledge to the user
   #Sign up to take on revisions to a section by changing the status and including your authorname in the ManualVXX page. This way, you don’t have to worry about someone else beating you to the revision and making you waste your time.
   #Read the Release Notes relative to your section.
   #Confirm existing functionality; in other words, make sure your topic still works the way it used to. Look for changes in the UI; fields moving around in panels, as a minor example. All the features that are already in the manual or reference guide (for 2.43 this are mainly the various new nodes) need to be checked against the final release anyway since some things have changed for sure (e.g. some nodes have altered user-interface…).
   #Explore and verify any New features. Construct a practical example, and take screenshots. Think “now why would I want to use this new feature?”
   #Draft a writeup of the new feature, in the Sandbox if major, or right in the wiki page if minor. Use the <nowiki>
2. REDIRECT Template:Warning/Working</nowiki> template if making changes in the wiki. Your text should be positive, accurate, give meaningful examples and practical advice on how to use this feature to get the job done. Use light humor, pictures, and speak in the first person. The first sentence of each paragraph and many sentences should start with “You...” or “Your”, express or implied, just like this paragraph.
   #Instead of starting from scratch, you might want to just Wiki-fy content from changelogs &amp; related pages.
   #Update version numbers in wiki-headers
   #Update (or add) screenshots if needed (there was a nice guideline for how screenshots should look .. e.g default theme etc.. link anybody?)
   #Grab a buddy and have them review your work.

The first step of updating the wiki for new versions is always to visit the Release Notes (in this case Release Notes/Notes243). All new features listed there (and the content provided on both, the Release Notes and the changelog on blender.org) need to be transferred. <!-- Redundant (already said above!)
And all the features that are already in the manual or reference guide (for 2.43 this are mainly the various new nodes) need to be check against the final release anyway since some things have changed for sure (e.g. some nodes have altered user-interface etc...)
-->

Don’t ASSUME that the reader knows even minor functionality or will magically try a common keystroke on their own to see if it works. Programmers love to play around, but Users are usually afraid they will break something and hesitant to just whack around. So, explain all the functionality available, not just some of it.

[edit] Progress Reports

Our community goal is to have the User Manual updated within a month after actual release. The following pages have been created using the above process:

• Meta:Wiki Tasks/Manual243

[edit] Template for Wiki Tasks/ManualVXX

Current languages are defined by the Languages template. When creating the Manual to-do list by section, copy and paste the contents of this page to create headings for the new release page. Then copy and paste the TOC for each language where appropriate. Edit the TOC as described above (adding the To-Do status template) to create the initial To-Do and signup list.