LineEditor documentation

Hiya,

I’ve been trying to put together some proper documentation for LineEditor (https://github.com/philpem/LineEditor). I’ve got the structure of the documentation and the SWIs but it’s the prose that describes what it does, how to use it and how you configure it that I’ve not got. I’ve read the documents that come with it, and heck, I had used it for years, but honestly it’s hard to write something official from the text files that come with it.

Given time I’d certainly have a good go at it, but I’m lacking in time right now. So I decided ‘what the heck, let’s ask if someone wants to give it a whirl’.

SO…. if you fancy it, let me know and I’ll give you copies of what I’ve got right now, access to the git repo with the docs in and any other help you might need to make it look good.

What do you need to know to be able to do this?

• English :-) (sorry, that’s what I’m writing in)
• How to describe what piece of software does.
• How to find out what it does when the documentation doesn’t tell you (that is – the docs don’t, so you’ll have to play with it, or look at the code to see what the intent is).

For preference it is good to have:

• The ability to use git (but not required, we can just exchange files if necessary).
• A linux system (’cos we can use the native tools there, rather than the RISC OS ones, but again not required).

Why am I doing this? I started to create the documentation to be able to have a concrete example of a 3rd party component to document. But then I found I don’t really have the time to finish it, and… might as well give someone a shot at it.

English :-) (sorry, that’s what I’m writing in)

You might drop in a smiley, but it’s actually quite true – knowing English doesn’t necessarily mean that one knows English well enough to write unambiguous documents with clarity.

In a story (fiction) I’m writing, it takes a few read throughs to notice and correct cases where something happens (she fell off her chair) and it’s not clear who (this she or the other she) it relates to, meaning the sentence needs to be rewritten. And there’s probably stuff I’ve missed…

Indeed, but I’ll take anyone who can write documentation at the moment :-)

The point is that what’s in the LineEditor text files /isn’t/ documentation. And if someone starts with the idea that they’re writing documentation they’re on a much better starting point than what’s there already, so it’s got to be a step up. Like many things in software, it doesn’t really matter if it’s tat for a first shot – it’d be a starting point to work from.

Basically I wanted to set the bar low enough that people aren’t put off trying. If I ask for a technical author, then the number of people who are qualified in the community will be low to non-existant. Even the number of people who feel that they’re qualified will be low. So might as well ask for volunteers.

To take your example, you’ve been ambiguous, but you’ve got a framework from which to start and to improve it. When doing editorial passes over documentation you usually spot ways to improve things – or that you’ve written complete garbage. But it’s a lot easier when you’ve got something to start with. And that’s where I’m trying to go – have a look at the LineEditor text files… they throw in a whole load of domain-specific referencs to 4DOS and its behaviour, and tcsh, without actually saying what you should be expecting from those things.

Someone who can pick that apart and explain what it is, even if it’s not completely accurate, would be better than what is there right now.

Interesting.

About 3 years ago I looked at LineEditor and realised that I only ever used line recall and simple editing, and there seemed to be so much more it could do.

I got hold of v2.76 from somewhere and started to try to make sense of those files. I did not get much futher than separating them into parts and importing them to an EasiWriter document.

I soon worked out that it was something that I was never going to use myself and there was a mountain to climb. Much as I enjoy documenting, this was too much for me and I am afraid it remains so. ;-(

I’m willing to give it a try. I’ve written most of the Raspberry Pi pages for the ROOL wiki but I wouldn’t consider myself a technical author.

Other points of note:

• I downloaded the LineEditor source and generated the module using RPCEmu on macOS, so that all seems to be ready to go. I’ve not used Zap for many years, but the text files accompanying the LineEditor source suggest that it works with StrongEd, so that shouldn’t be a problem either.
• Git? Not used it, sorry. I understand there’s a steep learning curve…
• Linux – I’ve got a few (well, 3 actually) Pi 4 models sitting here doing nothing. It would only take a few minutes to install Raspbian, although I’m not had too much experience with Linux itself (I’ve been using macOS rather more in recent years).

I wouldn’t consider myself a technical author

I wouldn’t consider myself a technical author if I hadn’t been employed as one for nine years, but I wasn’t any different before, during, or after that period. If you’ve written technical stuff that people find useful, then you’re better than the average technical author…

If you’ve written technical stuff that people find useful, then you’re better than the average technical author…

I was in college with a guy that had the declared career objective of being a technical author.

There was one single guy on the course who could take the simplest things and phrase the wrong explanation in a wonderfully believable way. He wasn’t playing, he just didn’t know.
Yep, one and the same.

I said then that it explained the content of many manuals.
I wonder, is that why techies don’t read the manual except as a last resort?

take the simplest things and phrase the wrong explanation in a wonderfully believable way

Acorn tried to cash in on the success of the BBC Micro Advanced User Guide by publishing what they thought was something similar for the Master. It was full of very plausible things for the gullible.

My favourite one was “The A register is the X register and also the Y register.”

One (who shall remain nameless) wrote “Please stay off drugs whilst writing documentation.”

Bizarrely, there only seemed to be one copy, so I deleted it from the file server and blamed a hard disc crash when manglement asked. They got someone else to redo the Reference Guides…

I wonder, is that why techies don’t read the manual except as a last resort?

It’s the job of every designer – hardware, software, user interface – to design so that it isn’t necessary to read the manual. Using the product should be obvious.

Easy to say, difficult to achieve.

User documentation is difficult. I’ve spent a not insignificant time at work editing the installation manual for a major application that the company wrote. I’m pleased to be able to say that I made it much better. At the same time the programmers were doing all they could to automate the installation. Overall, our efforts made it much easier for anyone installing the software.

I do remember that it was difficult to get the other members of the team to read the manuals – proof reading doesn’t seem an adequate name for it, as really what’s necessary is not so much the spelling and punctuation, it’s the higher levels – what’s unclear or outright wrong, and – even more difficult – what’s missing. A programmer is too close to the app, and will usually fail to describe things that he’s done so often that it’s gone to the back of the mind. No-one wants to read them!

and will usually fail to describe things that he’s done so often that it’s gone to the back of the mind.

Or the programmer is so bored with something that ought to be bleedin’ obvious that the instructions last for about half a page before turning into a four page treatise on River Tam’s relationship with Shepherd.

I eventually deleted that because, well, it had nothing to do with the software in question. Although, in hindsight, maybe I should have published the treatise and deleted the software? ;-)

Stuart Painting wrote:

I’m willing to give it a try. I’ve written most of the Raspberry Pi pages for the ROOL wiki but I wouldn’t consider myself a technical author.

Excellent. I’ll happily take anything I can get :-)
There’ll be a little learning curve on how the documents are structured, but I’ve written notes on how to update things and (largely) it’s pretty obvious (though I would say that…)

Other points of note:
bq. * I downloaded the LineEditor source and generated the module using RPCEmu on macOS, so that all seems to be ready to go. I’ve not used Zap for many years, but the text files accompanying the LineEditor source suggest that it works with StrongEd, so that shouldn’t be a problem either.

Should work with the TaskWindows on both, and at the GOS and shell prompt (and in BASIC, etc).

* Git? Not used it, sorry. I understand there’s a steep learning curve…

It’s an advantage more than anything else. We can update through a web browser, or by exchange of emails. Or some hybrid thing. We’ll see.

* Linux – I’ve got a few (well, 3 actually) Pi 4 models sitting here doing nothing. It would only take a few minutes to install Raspbian, although I’m not had too much experience with Linux itself (I’ve been using macOS rather more in recent years).

Ah, if you have macOS that may be simpler in some respects as that’s the system I use primarily – I assumed most people would have access to Linux rather than macOS. On the other hand, I’ve not done any work to get the build working on ARM Linux so that would actually be a little more fun.

Drop me an email at gerph@gerph.org and I’ll set you up with access to the repository where the sources live and the CI system runs, together with what I have so far (which is ‘meh’) and any other guidance you need.

If anyone else is interested in helping with this or other things (there’s a document describing ZapRedraw that could do with tidying up!) let me know.

proof reading doesn’t seem an adequate name for it, as really what’s necessary is not so much the spelling and punctuation, it’s the higher levels – what’s unclear or outright wrong, and – even more difficult – what’s missing.

Amen to that! That ought to be written in BIG, BOLD LETTERS in the job spec for everyone involved in producing documentation (or academic papers, publishing which was my previous incarnation). And 85% of them would still stress about the spelling and punctuation and totally miss important errors, inclarities and omissions. It’s what proof-reading is supposed to be about, really.

Rick’s point about it not only being what’s missing, but also what’s superfluous, is a good one too.

proof reading doesn’t seem an adequate name for it, as really what’s necessary is not so much the spelling and punctuation, it’s the higher levels – what’s unclear or outright wrong, and – even more difficult – what’s missing.

An ideal document is one with all the pertinent information and none of the “fluff”¹ – which is my label for superfluous so manglement can understand, sometimes.

¹
Sadly, “manglement”(as Stuart S. aptly puts it) like the fluffy bunnies bits of documents, while my colleagues and I like facts.

all the pertinent information

A fight I never managed to win in academic publishing. “Those bits are irrelevant.” No, what you mean is that they don’t support your conclusion…

(That was in Psychology. For some inexplicable reason it’s a fight I never had to have in Physiology. It may have existed between the authors and the reviewing editors, but it never made it as far as the production editors.)

There are two other problems I think with writing documentation.
1. There are a number of different thought processes people use. So what one person finds easy to follow another even with the same level of technical knowledge might not.
2. Writing something that both a novice and an experienced computer user would find clear is difficult. I recall many years ago two buyers comments on the manual that came with an Amstrad PCW9512. A computer novice thought it brilliant and very easy to follow but an experienced computer user said he thought it the worst manual he’d ever read. I suspect the later skipped parts he thought he knew, but they may have contained key information of how the Amstrad differed from his assumptions so was on faulty foundations from then on.

1) is an insoluble problem really, although the solution to (2) can help.

The solution to (2) is to have 2 (or more) levels of documentation – “User Guide” and “Reference Manual” is a common split. I think Acorn used to be fairly good at this, and I think we were fairly good at ARM when I was there (not, I hasten to add, because I was there particularly). Whether they’re still good I don’t know, I’ve not looked at ARM documentation much recently.

There’s always a problem of scheduling: essential documentation has to go out with the product, and the product wants to go out as soon as it’s ready. It’s bloody difficult to write good documentation of a product that doesn’t actually exist yet.

It is not quite the same as proof reading but I have had some experience of helping people with their English.

“User Guide” and “Reference Manual” is a common split.

The former is harder to write, IMHO. There is always the temptation to give out too much information too fast. Then there are cultural differences to be taken into account. Mathematical textbooks in the USA tend to be huge weighty things, compared to some of the slim products of small publishers in the UK – a difference that I always put down to the fact that students in the USA were more likely to have cars than bicycles. But the physical size of a document does not necessarily translate to more information. Some of the best mathematical textbooks have been informal notes by physicists, written to supplement seminars. Nowadays we have so many more media and formats: YouTube videos, web-pages, etc. I like to have paper versions to fall back on, but I think HTML/CSS offers the most in flexibility and accessibility.

The former is harder to write, IMHO.

Absolutely!!!

I think HTML/CSS offers the most in flexibility and accessibility.

And again!!!

I was looking today to see if I could get more mileage out of LineEditor, but was stumped by the explanations in its text files. Then I found this thread, and wonder whether Gerph + Stuart P have come up with anything yet.

Whether or not they have, I would put myself forward as someone willing to offer effort to the project to document it better. I too have access to MacOS which Gerph mentioned above as possibly useful, though I don’t run RPCEmu on it like Stuart does.