From BlenderWiki
Documenting
Release notes and Todo list
Then the release comes, and the documentation might well be out of phase with current release. How to address this?
Is it the developer that have to document? Or the documenter have to test and ask the developer?
The Release Notes are based on svn log, and the reader has to switch between CMS and wiki...
At this stage the best thing would be to place a plain copy of the relevant part of Release Note for each section of the manual (and to create new parts if needed), in order to have a "complete" documentation the release day itself. Then let the people take releases notes and elaborate on them in a true Manual/Reference.
Example:
- We place the piece of 2.49 release note relevant to rigging under /Manual/Rigging/2.49_Release_note
- Together with the commits log in a page like /Manual/Rigging/2.49_svnlog/
- That is the start for editors to add informations
- 1 day after the release the Mnual has the new infos in the right section
- the reader doesn't have to merge informations from CMS and wiki in his mind :)
<bebraw> sometimes it feels like release notes try to make up
for absence of real docs
<mindrones> it could be: imagine this thing as dictionaries ok?
<mindrones> page_about_argument_X[2.48]=page_about_argument_X[2.47]+release_note[argument_X]
<bebraw> okay. so release notes provide extra information for
real manual that is then added there?
<mindrones> you copy the RN and people go ahead
<bebraw> the basic idea is cool
Actually once we have release notes in place, we update the todo list.
<bebraw> atm there has been a TODO list at use
<bebraw> note that not everything (tiniest fixes/features) may not
be mentioned at the release notes (should they be?)
<bebraw> okay. how do you signal for the users to expand
the pages?
<bebraw> is there some explicit mechanism or does it just "happen"?
<bebraw> there probably has to be a way to make it easier
for a potential documenter just to jump in (current
TODO tries to do this)
Categories and tags
- First problem is that many pages aren't categorized at the moment (2000 pages out of 4400...) and this alone make categories unuseful, since they don't represent the whole wiki.
- some categories are duplicates, like Category:Snapping and Category:Snap for example
- Wiki has Categories but not Tags, as in blogs. To do tags you need to categorize the categories...
The best thing would be to define Manual chapters (or even paragraphs, we'll see) titles as "Categories" and every other category as "Tags", that is:- Manual structure define the "Categories"
- all differenr categories are under the relative "chapters", and have to to be seen as "Tags"; we may use as a convention that all 'real' Categories are in capital letters, and tags are normal text. Problem is: changing a title in sstructure gets you in troubles with categories. This should be managed automatically.
- If we go for the Form extension we should let users know there are already similar categories, and maybe on some situations, like page creation in Manual/Tutorials/..., we should impose to choose among predefined categories and let users TAG things if necessary
- Semantic wiki seems the perfect solution to address the tags problem, and offers cool search tools based on properties
Versioning
This is related to Reference, Manual, Tutorials, so it applies to pages, images, python scripts and plugins, and links maybe (especially downloads of blender and scripts).
Versioning (whole pages)
If people read on a unique maual, some feature might be unchanged so there's no need to document those.
So how to distinguish old but still up-to-date pages from pages out-of-date? At the moment we can add a Category, but this is not much effective to separate contents.
From a chat with bebraw:
<bebraw> there's an evil trick (takes some parsing) that can
be this painless for the user
<bebraw> you basically put available versions in template and
then check for each if the page happens to exist (and
then show if it does) :)
<bebraw> the common part can be a template itself (not sure
if this is the cleanest solution though)
<bebraw> in mediawiki you can compose pages out of pages
(using regular pages even?)
<bebraw> i think current wiki does that in node parts... gotta check
<bebraw> basically the idea is that don't duplicate anything
you don't really have to
<bebraw> see http://wiki.blender.org/index.php/Manual/Using_Compositing_Nodes
and {{Manual/Using Nodes}} :)
Versioning (parts of pages)
The same page might have some section up-to-date and some others out-of-date.
How take this in account? Simply editing the old content means we loose historical documentation, especially because people put efforts in documenting :)
Versioning (python scripts)
Some script needs a Blender version AND a Python version
Discussion
Versioning (images)
Since most of the images are Blender screenshots, we should catalogue them in the appropriate section, in order to let the user to recognize the version just reading the image URL.
Is it possible to add a blender version menu at the upload file form and put the image in the appropriate place and then use this folders option?
Also, during the chat with bebraw we talked about automatic screenshots generation, per feature.
<bebraw> We discussed about generating screenshots for the wiki automatically. This is entirely possible but it has to be taken in count in Blender's design. It is somewhat trivial to render into image using OpenGL. Anyway this is probably something that could be made a development goal for Blender at some point? (Probably not the most needed feature but still. :) )
Versioning (possible solutions)
- The day of the release, we should copy the whole Documentation structure (not development, not Meta) into a branch named with the PREVIOUS blender version, in order to have the same link refered to the PRESENT Blender. Example: it's the 2.49 release day: we copy the whole wiki to a "2.48" version and that will probably remain unchanged because people will be addressed to the old links, that now are referrred to 2.49, so that everything seems like before, but we have a wiki per-version. (The difference is in the url of course.)
- Add a small blender icon and blender version text with a colored background, the same as we have in blender, with a popup thing once you click on the blender icon, to show the splah screen. This would be funny and useful too.
- Add a menu-list to let the users add the blender version to a page, quickly (screenshot). If there isn't a page under the relevant version in wiki, a server should copy the page under the right place.
This can be done with templates.
- Use of Dynamic Page List (DPL) for assembling pages based on older parts of manual where it is still actual. Each release we create a new branch with DPL, in such a way that a day after the release each page of the new manual are autogenerated. From then on only parts that need editing will contain text.
Possibly even talk pages should be copied like this, so that comments outdated for a certain release can be erased. This will also permit to put the link to splash popup :)
- NOTE. in Special:Version I see that DPL2 is installed, but the link points to DPL, which version is it?
Localization / Translation
- Structure of the manual is not always the same between languages, so we need a uniformity, useful to make some automation later.
- If a page exists in a localized section of docs, it is translated, ok, but how?
--> Add a rating system might give an idea of how it goes. Same for a comments system. There are wiki extensions for this. - actual scheme is Meta/i18n#Naming which reports "Experiences of other Wikis sats that localization are best kept separate to avoid confusion (and possibly people starting to translate an English page which should stay in English!"
- do people modify contents in the translated page? or they just translate the variations in official english page?
this is related to the versioning problem also, that might be solved with structure consistency among pages - how do other wikis handle the issue?
<bebraw> for proposal it probably makes sense to look at some well
known wikis to see how they handle i18n and then
compare the relative strength/weakness of different solutions
<mindrones> I've seen some page/ar around in the web, so /ar instead of .ar
<bebraw> they seem to use that at mediawiki,
http://www.mediawiki.org/wiki/Manual:FAQ/it
<bebraw> in a sense that's a nice way (just one tiny addition
to end of url)
<mindrones> wikipedia use second level domains
<mindrones> http://fr.wikipedia.org/wiki/Accueil http://de.wikipedia.org/wiki/Wikipedia:Hauptseite
<bebraw> btw xsi wiki is probably worth a look too http://softimage.wiki.softimage.com/index.php/Main_Page
<mindrones> yes, but they don't have 4400 pages and they are a company
<mindrones> not made buy that amount of people I guess
- Separate languages
with namespaces: Example: index.php/FR:Manual/Mesh-editing, index.php/DK:Tutorials/Creating-a-tennis-ball
Since searches are usually made in (Main) namespace, this would have the benefit that so if the user doesn't find something he/she will be forced to search in specific namespaces. This will automatically make him/her aware of the fact there's a namespace for that language.
Also, a search in a limited namespace is more efficient because many pages are not completely translated (they still contain english words) so they are found in searches giving duplicated results.
I guess isolating searches like this might lower the stress on blender's server, ?
with subdomains (wikipedia.org): Examples: http://fr.wikipedia.org/wiki/Accueil http://de.wikipedia.org/wiki/Wikipedia:Hauptseite
For blender wiki it would be de.wiki.blender.org, it.wiki.blender.org, ... Is this possible? If yes, is this even useful? There would be a way to send the user to search in language-specific site, this is more complicated I guess.
- Proposal:
- all languages under a "localized" folder with localized structure identical to the english one, but without untranslated pages, OR
- untranslated page should be inserted with templates like bebraw suggests, but possibly with an addictional template indicating that the page is a clone of the english one
- possibly untranslated page should have a different css
- link to untranslated pages might have a different color: actually is blu for "page exists", green is for "page doesn't exist yet", maybe yellow might be "untranslated page"
- if we have the same identical structure among languages (and possibly namespaces and contexts (manual/tutorial/reference/...) we might put a line with small international flags to say if the page is translated or not (not translated --> desaturated colors). If not, the link to untranslated page sends you to a new page in sandbox as <path>/page-work-in-progress, that users will have to move to <path>/<real-page> once it's completed. It would be great to have a menu-list near the "save page" button form to choose "translation completed", "translation in progress"
<bebraw> The updating issue (translated version is not in sync with the original one) is somewhat mitigated thanks to the possible versioning scheme used. The translated versions ~have~ to be checked out always when a new version of Blender comes out. During that process the pages can be updated to match the original source.
Occasional contribution
Let's remember that readers are a lot more (many order of magnitude) than documenters, so let's try to get from them what's reasonable :)
Problem: people might not desire to sign in, but they may have the will to help just a bit. Fixes, typos, link corrections, even language mis-translation or bad english could benefit from letting people help. The major benefit might be having anonymous readers just flagging a content as obsolete, or problematic, and maybe indicating which version is this referred to.
Possible solution:
- Anonymous access, with a strong captha to avoid spam. There are reCaptcha and others available extensions.
<bebraw> captcha on edit confirmation works :)
- The anonymous contribution should be restricted to the Talk_page. In this regard, I've tried a very useful wiki extension to do this. #TODO:link
<bebraw> I think this might lead to some sort of editor scheme
(someone has to read through all "commits" :s)
Page scheme
- If the user wants to create a page, he should be guided through a form, in order to let him know there might already be sections relevant for his entry. This would avoid having 300 pages on the root (like we have now), without a proper collocation in the structure and probably difficult to reach unless linked somewhere. There are extension to automate a bit the process of inserting pages. #TODO: form extensions links
- Also blocking the structure of the page would be useful also for certain types of pages, like Feature requests, Scripts catalog, what else?
Also, a form would remind the user that the page might fit in one or more categories: in the form we should place the list of categories in a multi-choice (ctrl-click) menulist.
Well categorized contents are easier to find.
<mindrones> http://vinismo.com/en/Wine_Guide
<mindrones> click on add a wine, up left
<mindrones> read here http://vinismo.com/en/Vinismo:Wine_pages
* bebraw knows nothing about wines :)
<mindrones> :) oh no!
<mindrones> the point is they have a scheme for pages
<bebraw> what does a scheme mean in this context?
<mindrones> it is this http://vinismo.com/en/Template:Wine
<mindrones> AT LEAST each page have that
<mindrones> those points, equal for each page, too schematic
maybe, but I was thinking at the idea
<bebraw> okay. got it. i wanted to have something like that
for my project wiki to ensure each page has certain
data on it automagically
<mindrones> peter schlaile also asked for a form to have users
upload requests
<bebraw> yup. i can see that working well in their case
<mindrones> in our is less likely?
<bebraw> i'm not exactly sure
<mindrones> feature requests for example are like wines
<bebraw> yup
<mindrones> also references, an image, a shortcut, a description
(short), maybe an area of interest, a view, ??
<bebraw> that's a nice way to enforce certain kind of
structure i think
<mindrones> yes
Ease of use
A WYSIWYG editor would help people to jump in and edit. That's it.
I use FCKeditor, on my Plone site and on a local mediawiki installation and that's very useful to type and organize the page easily and fast.
JesterKing is working on it, so let's hope very soon we can use it :)
Removing old blocking warnings
As an example, this warning has been there for 10 months (now I have removed it :). This is blocking for potential occasional helpers. Bebraw suggested to use some script to check for the age of warnings in order to remove older ones, and I agree.
<bebraw> the sign is scary though (there are probably
maintenance scripts that can remove those if they are too old?)
