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