How to recommend / suggest changes to LO Base Help files?

English
, ,
#1

Hi all,

As a result of a couple of recent questions I feel inspired to suggest several changes to the text in the LO help system.They would be one or two whole new pages to the LO Base plus small changes to existing pages to link the new pages in.

I would appreciate some advice here before I do so. I want to help and with the huge complexity of LO I do not feel up to software maintenance. I have done maintenence in a small way on end user documentation in the past and feel I could contribute in that way. There are a couple of pages in the qubes docs that I edited back in April 2018, for example – I’m @trueriver on github too :slight_smile:

I want at least some mention of the new pages in the help system, as the current help both in LO 6.4 and the latest online help completely missed three options for data import from a .csv file. I recently discovered these new ways of doing this, and at the very least I would like a link from the help files to the answer on this forum.

I found this page suggesting I write my suggested additions in Writer and email them in. Tah is certainly straightforward enough. Is this up to date advice though?

Secondly, Am I right in assuming that the word “latest” in the url Importing and Exporting CSV Files is actually the help given for the latest LO release?

Third: How would I also ask for the new info to be backported to the help for earlier releases? Or are these now frozen>

Fourth: How are comments passed backwards and forwards between the docs team and the new documentation volunteer? By email? or will they induct me into a GIT repository or suchlike? Or something else?

Finally: does anyone here have any advice to give me to improve the chances of my suggestions being adopted? I have added docs to other software systems in the past, so I am not a total noob at this; so I am more looking for advice specific to LO help rather than generic help on writing help for software users.

1 Like
#2

The correct landing page that you referenced in your question also has the Editing Help pages directly in Gerrit link, which is what I’d suggest you to do. It’s easier, faster, better in any sense.

And basically, it solves everything you asked. The chances that any contributions are accepted by the project are always very high (we welcome any contribution); the gerrit workflow is where all discussion and iterations takes place; backporting happens there (but the help pages changes will not be backported, because that would mean the requirement to translate, which we don’t do in released versions).

The “latest” in the URL means “latest released”, which for now means 7.4; and there are already 7.5 in release candidate stage, and 7.6 as a trunk development.

1 Like
#3

Thanks Mike :slight_smile:

Yes this looks like the way to go, much better than emailing something out

. I am the point of checking out the existing code and creating a new branch.

I think that I do NOT want it to be a private branch because I do want others to see it and potentially comment on it.

What to call it? I am considering the branch name import-csv-to-base and will stick with that name unless you strongly suggest something different.

I have no idea what to put in for the SHA. Not having used gerrit before I do not have the script that sets things up. Do I just leave this blank for now?

Warmly
River~~

#4

Oh, I am already stuck. It will not accept an empty destination branch, and I can’t work out which of the many existing branches I should choose to work on the currently published one.

#5

Use ‘master’. Just as suggested on the wiki page :wink:

#6

oops :roll_eyes: missed that

#7

Hi Mike:

I have amended a note in one page and (I think) published it. For me it shows up here.

I now have two more questions for you. If I wanted to add a new note instead of adding text to an additional one, do I have to generate a new paragraph id, or do I omit it and trust the system to add it?

And I added a link to the text that would brong folk back to a question in ask.libreoffice. Is that allowed? I just pasted in the full link for now (including the https://) to see what happens, but what is the preferred syntax that gets translated into an HTML <A…> tag please.

Sorry for these noob questions… I will be up and running properly soon

#8

Don’t forget to mark it active - until then, no one would review it, unless you ask explicitly.

Generate a new one: simply get any random id, e.g. take a previous ID, and increment by 1 (making sure that the result is unique in the file - duplications are OK across files).

Please don’t. If wanted, create a FAQ in our wiki, and link from help to there. See this example of such a FAQ. Ask is not a good place to link from help; among other things, it’s simply chaotic, and you can’t even guarantee that readers will find appropriate language (wiki is moderated much better).

#9

Then I am glad that I didn’t yet mark it active :slight_smile: because I did wonder what the policy was. I will have to make further changes before activating it.

How do I see the HTML that the amended page will generate, or indeed see that rendered in my browser?

#10

Possibly Documentation - The Document Foundation Wiki could help (I am not a Documentation team member, and I myself never managed to get such a preview for myself). Maybe @ohallot could help better.

Documentation of keywords and hyperlinked concordance
#11

Hi @trueriver

Welcome.

For discussions on Help contents, which are very much appreciated, we recently added a category in our Discourse instance for the purpose.

https://community.documentfoundation.org/c/documentation/localhelp/15

Please feel free to bring your ideas and contributions there.

Kind regards
Olivier

1 Like
#12

hi @ohallot thanks for the welcome.

I am now getting a bit confused about all the locations where documentation exists for LO.

Is the discourse instance which you linked above the same as any of the following, or is it yet another place where I can make my views on the docs know?

I have this year already discovered:

  • ask.libreoffice
  • TDF wiki
  • gerrit for direct editing of the online and built-in documents

My inclination is more towards writing the docs I want than towards asking others to do it, hence my interest in gerrit and the wiki. I have today made my first tentative creations on each of those.

I wonder if you would be willing to give a two or three sentence description of what the discourse category is intended for?

#13

Hi @trueriver

If you have missed the initial post of the category, here is it for your convenience.

https://community.documentfoundation.org/t/about-the-libreoffice-help-category-read-me-first/931

But feel free to ask for guidance, we are here to help.

We also have 2 more services for the users guides: https://books.libreoffice.org and https://documentation.ibreoffice.org .

Currently documentation is scattered into many services, because - mainly - there is no “one size fits all” and the community tend to stay in its comfort zone. The Help is part of the product and follows release schedule, uses gerrit and follows development rules and timetable, quite unfriendly actually. On the other hand, the wiki and our books are released at the pace of the community availability.

The LibreOffice Help is written in XML and requires a building installation to get results, besides knowledge of the XML quirks. If you want to suggest a new writing of a Help page you can either open a bug in Bugzilla and add your suggestion or start discussing the topic in the forum above, so we can craft a better text for the Help more fluently. If necessary, I can then convert to XML and properly give credits to the authors. Note that the Help historically contains a reference guide as well as a user guide and these are different beasts.

Last but not least we also hacked a XML editor for quick checks at LibreOffice XHP Editor

Regards
Olivier

Impressum (Legal Info) | Datenschutzerklärung (Privacy Policy)   Content on this site is licensed under a Creative Commons Attribution Share Alike 3.0 license.