[scribus-dev] Scribus documentation translations temporarily removed from builds

[Louis Desjardins]

2010/11/30 Craig Bradney <cbradney at scribus.info>

>  On 11/30/10 11:40 PM, Louis Desjardins wrote:
>
> 2010/11/30 Craig Bradney <cbradney at scribus.info>
>
>>  On 11/30/10 11:26 PM, Louis Desjardins wrote:
>>
>> 2010/11/30 Gregory Pittman <gpittman at iglou.com>
>>
>>> On 11/30/2010 02:24 PM, Louis Desjardins wrote:
>>>
>>>>
>>>> I am not too sure to understand either just how the doc workflow works.
>>>>
>>>> Can we translate the doc? can we help write it? can this job be on a
>>>> wiki? (so we can work on it step by step, from time to time, alone or in
>>>> a group of people). How can we improve the doc workflow, in fact.
>>>>
>>>
>>>  Anyone can translate the docs. Simply pull them out of their location
>>> and edit away. Usually what I see people do on the wiki, which makes sense,
>>> is to copy the original, then stepwise work through the html file paragraph
>>> by paragraph, leaving the tags other structure in place as you go.
>>>
>>> The structure of the docs directories and files is pretty
>>> straightforward, as is the XML file that forms the index. I have sent
>>> Christoph anything I make, since he has commit rights and I don't.
>>
>>
>>  Do we need commit rights to edit an online doc file? Or to submit a
>> translation? My understanding of this is it’s tied to the application only
>> by a URL. Thus, in no way does that affect the code. It’s a simple link to a
>> website.
>>
>>
>>  You download the file from SVN, translate it, submit it to Christoph so
>> he can commit it.
>>
>
>  What do I do if I want to help write the file on the first place?
>
>
> Write the content in plain text format and send it to Christoph.. add the
> HTML tags if you wish for bold, italic, paragraphs etc if you wish. He can
> clarify what he would expect easiest/best/harder/worse.
>
>
>>
>>  Can we turn this into a wikipedia-like way to go? If for some reason
>> someone makes an error and mixes things or deletes some content, we have
>> ways to return to the previous stage. I see a lot of disadvantages at
>> pulling out a file, edit away and then pushing it back, while there are ways
>> to work in a collaborative (and sync) mode.
>>
>>
>>  We have SVN.. which contains the history of Scribus for (almost) ever...
>>
>> I do not believe we have a nice way of extracting from a wiki to our html
>> format.
>>
>
>  There is something I don’t get, obviously. :)
>
> See the SVN checkout info on docs.scribus.net or the wiki.
>

Do you mean this page?
http://docs.scribus.net/index.php?lang=en&page=install1

>
>  Why should we extract something? When we edit a wikipedia page, we edit
> the actual page that is shown to the rest of the world.
>
>  The only purpose I would see that would require to extract something is
> when we would like to produce a book out of the content of the online doc,
> using a Scribus template for instance. Then, yes, we would need to extract
> something.
>
>
> We have no intention of producing an online site only.
>

Maybe it’s time to revisit some old ideas.


> Christoph is writing documentation
>

We have to ask ourselves why is writing the documentation in the hands of
only one individual? Wouldn’t it be better if this effort was distributed?
Only a question and NOT a judgement on the work done.


> that appears under the Help->Scribus Manual menu entry, as distributed with
> Scribus.
>

Why do we still have to distribute the application with the doc files?
(maybe the answer is just below, my guess)


> We have a process that automatically checks out those HTML files and does
> some data massaging into the format you see on docs.scribus.net... so.. from
> 1 HTML file we get a shipped HTML file with the installed software, plus the
> online version at docs.scribus.net.
>

If I get it well, the point here is to make the doc available when you’re
offline too, right? But in fact this is probably why it’s so unappealing to
think of the doc with 49 localized versions. It would be huge, and if we add
to this the screenshots, it will be even bigger. If the doc is online only
and not shipped with the application, everything will be easier and lighter,
don’t you think?

>
> There is, and never has been, any intention of producing a book from this
> content.
>

I understand that there is and never has been such intention but this is
exactly what I suggest for the future! Some people need a book — that is
understandable and acknowledged — but why would the content of this book be
different (or so different) than what’s available on the website is one
question I ask. It would simply be repurposing of the same data.

Again, I think that there are some bugs into the doc workflow and I suggest
ways of making things better.

I think that the wikipedia way is more appropriate for documentation as SVN
is probably more suitable for code.

Louis




> Craig
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.scribus.net/pipermail/scribus-dev/attachments/20101130/8433ad8a/attachment.htm>