[Bf-docboard] Documentation status and upgrade proposal

[Campbell Barton]

Hi, update on the migration,

I've just got a basic wiki2rst script working and committed into:

  https://github.com/ideasman42/blender_manual/blob/master/_tools/wiki2rst.py


I've uploaded the result of many pages batch converted with both *.rst
and *.mwiki
so you can see before and after:

  https://github.com/ideasman42/blender_manual_wiki2rst

>From the script
----
# - headings
# - bold/italic
# - bullet points
# - {{Literal|Some Text}} -> ``Some Text``
# - {{Shortcut|Control|x}} -> :kbd:`Control-x`
# - {{Menu|Some|Menu}} -> :menuselection:`Some --> Menu`
# - [http://www.someurl.com Some Link]  --> `Some Link
<http://www.someurl.com>`_
# ... basic cleanup on text...
# - wrapping (with some tweaks so sentences don't begin at the end of a line)
# - stripping WIKI boiler plate {{Page/... etc}}, __TOC__
# - replace double -> single spacing
# - tabs -> spaces
# - unicode with ascii characters
----

In most cases we can't use the result `as is`, but it takes a lot of
the grunt work out of the migration.



Basic workflow:

Run:
 python3.4 ./_tools/wiki2rst.py
http://wiki.blender.org/index.php/Doc:2.6/Manual/Modeling/Metas/Editing

It will print the path that it writes to:

  Written: _output/modeling-metas-editing.rst

Then its up to us to cleanup modeling-metas-editing.rst and put it in
the right place in relation to all other docs.

On Sun, May 11, 2014 at 9:29 PM, Fade <fade_docboard_blender at ymail.com> wrote:
> Ha. I'm without regular internet for a few months (housing issues) and
> then everything changes! Awesome. Honestly, after some time away I
> wasn't terribly keen about working on the manual again for any number of
> reasons. The sight of a fixed width column for content in Campbell's
> example has me unreasonably excited.
>
> That being the case I am 100% in favour of switching. I agree that if
> the switch goes ahead, editing the content of pages as we move them
> would be a bad idea. However I think that a bit of restructuring/culling
> is important so that we start with a solid base to work from otherwise
> we'll just be inheriting the problems of the old wiki (which is a bit of
> motivation killer).
>
> Either way I'm keen to be involved
>
> On 09/05/14 07:24, Campbell Barton wrote:
>> @Gaia
>>
>> Yep, I suggest to replace old crap with new crap :), mainly to split
>> the project into manageable chunks.
>>
>> I worry if rewriting a manual and switching to a new platform are done
>> as one step it may take a lot longer (years even).
>> And if one fails (either the new system or the rewrite), we are left
>> with something unusable - a half written manual.
>>
>> If we try to switch to a new technology and fail, then we can blame
>> the technology... and try something else, or go back to what we have.
>>
>> If rewriting the manual fails, we can blame our own ability to write
>> :)... and still end up with better tools/technology and (somewhat
>> improved docs) - even if we dont manage to get all up to a higher
>> quality.
>>
>>
>> Something I want to avoid is to be in an unknown state for a long
>> time, while we move to a new system we probably want to freeze all
>> edits to the Wiki manual, but we should try keep that time period as
>> short as possible IMHO (weeks - some months max).
>>
>> I realize moving existing docs over may feel like a bad start, but at
>> least we can do this without long discussions on subjective matters
>> such as writing style and can even automate the process to some
>> extent.
>>
>> If we want to rip out chapters and rewrite after, then theres no
>> problems with that.
>>
>>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard



-- 
- Campbell