Re: Trying to re-generate the Documentation effort

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: Trying to re-generate the Documentation effort

Keith N. McKenna
On 5/30/2020 8:41 PM, Keith N. McKenna wrote:

> I should probably have my head examined but I am thinking of one more
> time trying to revive the documentation effort for AOO. One of the
> drawbacks is that most people that have started to help have left as
> there has been very limited availability of mentoring. I do not see this
> changing but I am hoping that by defining a new process we can reduce
> the dependency on mentoring.
>
> One idea for this would require that the MediaWiki extension be made
> functional again. This would allow for using Writer to create the source
> which could be stored in the git repository and then be transferred to
> the mwiki for easy online access. By storing the source in the
> repository it would give us better revision control over the
> documentation. Plus it may help relieve the mentoring problem as many
> more people are familiar with using Writer.
>
> Another would be to use Docbook, though this is not as appealing as I
> have no familiarity with it and it appears that there is a steep
> learning curve to its use and that would be a disadvantage to attracting
> new people.
>
> I look forward to any other suggestions that could move this effort
> along as it has languished for far to long.
>
> Regards
> Keith
>
Greetings All;

I unfortunately have no good news to report at this time. It is over 2
weeks since I posted the Proposal document to doc@ and there has been
zero response from the list except a couple from Detlef and Francis. I
will send out another reminder today and wait another week to see if any
responses come from that.

Regards
Keith



signature.asc (499 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Trying to re-generate the Documentation effort

Peter Kovacs-3

Am 02.07.20 um 17:18 schrieb Keith N. McKenna:

> On 5/30/2020 8:41 PM, Keith N. McKenna wrote:
>> I should probably have my head examined but I am thinking of one more
>> time trying to revive the documentation effort for AOO. One of the
>> drawbacks is that most people that have started to help have left as
>> there has been very limited availability of mentoring. I do not see this
>> changing but I am hoping that by defining a new process we can reduce
>> the dependency on mentoring.
>>
>> One idea for this would require that the MediaWiki extension be made
>> functional again. This would allow for using Writer to create the source
>> which could be stored in the git repository and then be transferred to
>> the mwiki for easy online access. By storing the source in the
>> repository it would give us better revision control over the
>> documentation. Plus it may help relieve the mentoring problem as many
>> more people are familiar with using Writer.
>>
>> Another would be to use Docbook, though this is not as appealing as I
>> have no familiarity with it and it appears that there is a steep
>> learning curve to its use and that would be a disadvantage to attracting
>> new people.
>>
>> I look forward to any other suggestions that could move this effort
>> along as it has languished for far to long.
>>
>> Regards
>> Keith
>>
> Greetings All;
>
> I unfortunately have no good news to report at this time. It is over 2
> weeks since I posted the Proposal document to doc@ and there has been
> zero response from the list except a couple from Detlef and Francis. I
> will send out another reminder today and wait another week to see if any
> responses come from that.
I can only look into the MediaWiki extension. Everything else I have to
leave in other trustfull hands.

I am cuzrrently occupied by work. So it may take a while. However I have
posted a docbook video with a toolchain Suse uses.

  It point out difficulties they have in the production. And give
pointers to other slutions. I realy can recomment the talk.



---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Trying to re-generate the Documentation effort

Carl Marcum
In reply to this post by Keith N. McKenna
Hi Keith,

On 7/2/20 11:18 AM, Keith N. McKenna wrote:

> On 5/30/2020 8:41 PM, Keith N. McKenna wrote:
>> I should probably have my head examined but I am thinking of one more
>> time trying to revive the documentation effort for AOO. One of the
>> drawbacks is that most people that have started to help have left as
>> there has been very limited availability of mentoring. I do not see this
>> changing but I am hoping that by defining a new process we can reduce
>> the dependency on mentoring.
>>
>> One idea for this would require that the MediaWiki extension be made
>> functional again. This would allow for using Writer to create the source
>> which could be stored in the git repository and then be transferred to
>> the mwiki for easy online access. By storing the source in the
>> repository it would give us better revision control over the
>> documentation. Plus it may help relieve the mentoring problem as many
>> more people are familiar with using Writer.
>>
>> Another would be to use Docbook, though this is not as appealing as I
>> have no familiarity with it and it appears that there is a steep
>> learning curve to its use and that would be a disadvantage to attracting
>> new people.
>>
>> I look forward to any other suggestions that could move this effort
>> along as it has languished for far to long.
>>
>> Regards
>> Keith
>>
> Greetings All;
>
> I unfortunately have no good news to report at this time. It is over 2
> weeks since I posted the Proposal document to doc@ and there has been
> zero response from the list except a couple from Detlef and Francis. I
> will send out another reminder today and wait another week to see if any
> responses come from that.
>
> Regards
> Keith
Forgive me but I'm not any expert on documentation or technical writing
but I'll offer my opinion.

I like markup formats for the ease of source control and revision
tracking.  I don't think binary files work well in this context.
I'm not real familiar with Docbook but it appears to be an XML format
which isn't all that readable on it's own but I also haven't
investigated any editors as I'm sure there are some.

My experience with online editing like our MWiki hasn't always been
great due to time-outs for example.

Lately I've been using AsciiDoc format and an editor called AsciiDocFX
(because it uses JavaFX for the UI) and I work right out of my project
source's local repo.

I'm not sure what our arrangement is with GitHub but my understanding is
that accounts get 1 github.io site and projects get unlimited pages
which are html.

For example on my GitHub code projects I have a docs folder that
contains the AsciiDoc text files and the HTML exports from the
AsciiDocFX editor. These files are tracked with Git along with the
project code.

So to give you a feel for it you can see a source example [1].
What viewing the file on GitHub looks like [2].
and finally the rendered HTML documentation site that updates a few
seconds after a commit. [3].

I have attached a screenshot of the editor and an exported PDF.

What you gain in revision control of text files you give up in document
formatting.  The final output will never look as good as using something
like Writer to do it all in so it's a trade off.
As a developer I'm comfortable using tools like Git for changes but I
don't know how most tech writers feel about it.

Unfortunately we also have hundreds of Dev Guide pages on the MWiki that
can't be viewed right now until someone can fix the MWiki extension for
some markup tags we use to write hyperlinks to the API's.
So I think the less we depend on custom extensions the better.
There seem to be a few markup converters like Pandoc that could help if
we get stuck somewhere.

[1]
https://raw.githubusercontent.com/cbmarcum/guno-extension/master/docs/index.adoc
[2] https://github.com/cbmarcum/guno-extension/blob/master/docs/index.adoc
[3] https://cbmarcum.github.io/guno-extension/

Best regards,
Carl







---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Trying to re-generate the Documentation effort

Keith N. McKenna
Hi Carl see comments in-line

On 7/4/2020 5:32 PM, Carl Marcum wrote:

> Hi Keith,
>
> On 7/2/20 11:18 AM, Keith N. McKenna wrote:
>> On 5/30/2020 8:41 PM, Keith N. McKenna wrote:
>>> I should probably have my head examined but I am thinking of one more
>>> time trying to revive the documentation effort for AOO. One of the
>>> drawbacks is that most people that have started to help have left as
>>> there has been very limited availability of mentoring. I do not see this
>>> changing but I am hoping that by defining a new process we can reduce
>>> the dependency on mentoring.
>>>
>>> One idea for this would require that the MediaWiki extension be made
>>> functional again. This would allow for using Writer to create the source
>>> which could be stored in the git repository and then be transferred to
>>> the mwiki for easy online access. By storing the source in the
>>> repository it would give us better revision control over the
>>> documentation. Plus it may help relieve the mentoring problem as many
>>> more people are familiar with using Writer.
>>>
>>> Another would be to use Docbook, though this is not as appealing as I
>>> have no familiarity with it and it appears that there is a steep
>>> learning curve to its use and that would be a disadvantage to attracting
>>> new people.
>>>
>>> I look forward to any other suggestions that could move this effort
>>> along as it has languished for far to long.
>>>
>>> Regards
>>> Keith
>>>
>> Greetings All;
>>
>> I unfortunately have no good news to report at this time. It is over 2
>> weeks since I posted the Proposal document to doc@ and there has been
>> zero response from the list except a couple from Detlef and Francis. I
>> will send out another reminder today and wait another week to see if any
>> responses come from that.
>>
>> Regards
>> Keith
>
> Forgive me but I'm not any expert on documentation or technical writing
> but I'll offer my opinion.
Feel free to offer because truth to tell neither am I. As a Process
Engineer I have written, contributed too, and edited technical
documents, mostly Standards for my former employers and process
documents for building finished modules from raw printed circuit boards
(PCB).

>
> I like markup formats for the ease of source control and revision
> tracking.  I don't think binary files work well in this context.
> I'm not real familiar with Docbook but it appears to be an XML format
> which isn't all that readable on it's own but I also haven't
> investigated any editors as I'm sure there are some.

My preference if at all possible is to use ODF files,mostly writer.odt
files, as the source documents. The product we are producing is an
Office Suite so what better way to create the source documentation with
the product and use that as marketing feature. The use DocBook would be
limited to a small number of individuals to create other alternative
delivery formats such as EPUB e-books.
>
> My experience with online editing like our MWiki hasn't always been
> great due to time-outs for example.

MWiki is not my favorite way to write documentation, but it is a good
way to present it online and OpenOffice.org did it and the beginnings of
the AOO documentation effort the decision was to go the MWiki route and
to actually write the documentation there a decision I believe was not a
good one and has turned out that way as the major driver behind it left
the project and we have had a difficult time recruiting people to the
effort.

>
> Lately I've been using AsciiDoc format and an editor called AsciiDocFX
> (because it uses JavaFX for the UI) and I work right out of my project
> source's local repo.
>

I looked at AsciiDoc and Markdown when I first started researching
alternatives, and decided against them as my initial preference was to
use AOO to create the source, but they could be used if using Writer
does not pan out.

> I'm not sure what our arrangement is with GitHub but my understanding is
> that accounts get 1 github.io site and projects get unlimited pages
> which are html.
>

I have started playing with GitHub a little bit but aside from a little
exposure to SVN and the CMS applet here, my last exposure to source
control was with deccms when I worked for digital equipment corporation
(dec). So far I have mixed feelings about it for .odt files.

> For example on my GitHub code projects I have a docs folder that
> contains the AsciiDoc text files and the HTML exports from the
> AsciiDocFX editor. These files are tracked with Git along with the
> project code.
>
> So to give you a feel for it you can see a source example [1].
> What viewing the file on GitHub looks like [2].
> and finally the rendered HTML documentation site that updates a few
> seconds after a commit. [3].
>
> I have attached a screenshot of the editor and an exported PDF.
>
> What you gain in revision control of text files you give up in document
> formatting.  The final output will never look as good as using something
> like Writer to do it all in so it's a trade off.
> As a developer I'm comfortable using tools like Git for changes but I
> don't know how most tech writers feel about it.
>
The problem of responding to that is difficult since we have no
experienced tech writers active in the Documentation Team. The only
feedback  I have gotten from doc@ was from Jean Weber and she left AOO
after a very nasty dispute with others on the project.

> Unfortunately we also have hundreds of Dev Guide pages on the MWiki that
> can't be viewed right now until someone can fix the MWiki extension for
> some markup tags we use to write hyperlinks to the API's.
> So I think the less we depend on custom extensions the better.
> There seem to be a few markup converters like Pandoc that could help if
> we get stuck somewhere.

I have started looking at Pandoc as a possible replacement for DocBook
as a converter as it appears to be able not only convert ODF to MWiki
but also the reverse from Mwiki to ODF which would be useful for
creating at least a Getting Started Guide for AOO 4.2.0 from currently
existing 4.x documentation on our mwiki.

I appreciate very much your thoughts and alternatives to what I had
proposed. I will take a closer look at your 3 URLs alter and reply
further was my thoughts

Regards
Keith

>
> [1]
> https://raw.githubusercontent.com/cbmarcum/guno-extension/master/docs/index.adoc
>
> [2] https://github.com/cbmarcum/guno-extension/blob/master/docs/index.adoc
> [3] https://cbmarcum.github.io/guno-extension/
>
> Best regards,
> Carl
>
>
>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>


signature.asc (499 bytes) Download Attachment