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: dev-unsubscr...@openoffice.apache.org
For additional commands, e-mail: dev-h...@openoffice.apache.org
