Author Topic: Manual for eFTE/2 / eFTE / FTE (Folding Text Editors)  (Read 907 times)

Alfredo Fernández Díaz

  • Newbie
  • *
  • Thank You
  • -Given: 0
  • -Receive: 4
  • Posts: 8
    • View Profile
Manual for eFTE/2 / eFTE / FTE (Folding Text Editors)
« on: November 29, 2017, 07:41:08 pm »
A long time user of FTE, tester of derivatives, and writer of extended configurations, I agree with every other user I've heard say that the worst thing about this fabulous editor is the lack of a good manual -- if there had only been one when I started using it...

A few days ago I finished writing a manual for the current eFTE/2 (99.5% of which still applies to the original FTE), thinking of what I would have liked to know when I started using it, and I thought it would be a good idea to find out if polishing it a bit for others out there is worth the effort...

Do you know FTE? Do you still use it? Would this make you try the editor? Do you think I should improve this manual? How? Am I better off devoting my time to other stuff?

From the Netlabs page where it belongs:
----8<--------8<--------8<--------8<--------8<--------8<--------8<--------8<--------8<----
It's still not a real manual, though, but a first step in having one.

If I were to set priorities, I would say the first thing to do is review the internal commands section for accuracy and adequacy of the descriptions. After that, maybe see if more useful information can be added to the task reference (Using eFTE2 / Standard text editing). Currently it is little more than a collection of links from menu items to internal commands.

Of course, the whole tutorial / customizing section can be reviewed for usefulness, and it might be useful to add screenshots here and there (all over the manual, actually) to further illustrate some points / examples.
----8<--------8<--------8<--------8<--------8<--------8<--------8<--------8<--------8<----
but those are my own thoughts. What are yours?



André Heldoorn

  • Full Member
  • ***
  • Thank You
  • -Given: 37
  • -Receive: 8
  • Posts: 235
    • View Profile
Re: Manual for eFTE/2 / eFTE / FTE (Folding Text Editors)
« Reply #1 on: November 30, 2017, 02:19:15 am »
Do you know FTE? Do you still use it? Would this make you try the editor? Do you think I should improve this manual? How? Am I better off devoting my time to other stuff?

</silence>
Despite of several non-negative answers, it's quite unlikely that new users will start using it because you've invested time in a manual. New users ought to be able to use an editor without a manual. Advanced users may like it, but the number of advanced users will be limited.

IIRC the distributions weren't that clear, which was the main reason why it took me several years to review and eventually install the right FTE files. Such a delay didn't promote it being used, because users had several years to get used to alternatives. IIRC, I do recall several FTE*.ZIP files and/or additional packages, and a lack of up-to-date important READ.ME files.

I guess writing documentation would come down to recording the knowledge of an experienced user. In the past a better installer could have helped to attract more new users, without e.g. having to download and install yet another manual package in the future.

Back to you. EPM is pretty powerful too. The number of times I've read and used a tip in an EPM tips & tricks-article will exceed the number of times I've looked for EPM manuals. If the number of readers is not important, then recording your knowledge could justify the extraordinary efforts, but you may as well write documentation for advanced users and make sure that it's not hard for new users o start using it. A quick search @ Hobbes results in 11 *FTE* files in /pub/os2/apps/editors, and I guess the WPI version got me going. Since this WPI file you've uploaded other files too. Updating the WPI archive may be better, and I don't know why fte_cfg_20170924.zip wasn't replaced. Perhaps try to reduce the number of updated files to 1. Now an user may have to check 11 unclear files to figure out what's required to install 1 FTE.

My $0.02.
<silence>

Alfredo Fernández Díaz

  • Newbie
  • *
  • Thank You
  • -Given: 0
  • -Receive: 4
  • Posts: 8
    • View Profile
Re: Manual for eFTE/2 / eFTE / FTE (Folding Text Editors)
« Reply #2 on: November 30, 2017, 01:26:57 pm »
If we should have learned something from IBM's Paradox of the active user besides that people don't want to read manuals, is that manuals are not there to make people use products, but rather to enable people's use of products to be, well, as productive as possible within given product designs. New users may be attracted to a product because a manual tells them how it works better for them than similar products, however.

I use NEPMD myself, and I used IBM-supplied EPM. It's not the 80s any more, so I expect any user to be able to use (e)FTE(2), (N)EPM(D), or any other text editor with pull down menus without reading a manual for that. File -> open, Edit -> Copy, etc., should be obvious to everyone by now, like using a mouse has become for the most part. Scratching the surface and trying out extra, non-obvious menu entries to see what happens is entirely up to users. But these programs go way beyond the basics common to all editors, and how to take advantage of that is often not self-evident. That's when the manual can make a difference. You may have a great one that even being incomplete gets you on track with what you can do and how (NEPMD), or a bad one that won't (EPM). Or, as was the case for FTE, you can be left out in the cold with a dry, cryptic reference to some 'internal commands' (?), and your curiosity. That is the gap I tried to plug with my first version of a manual for it, not more, not less. The question remains whether I did a reasonably good job, and whether it's worth to invest more time on future versions.

Regarding your other comments:

All the zipped FTEs  you can find at Hobbes work out of the box (I tried them all) -- unzip and run, no assembly required. Therefore, I would hardly have a problem with users developing their own extra/enhanced configs and sharing them (just like M. DeBusk or myself did) for others to try. I would hardly have a problem either with developers picking that up and bundling it with a newer version, just like M. Greene did: you never had to "download and install yet another" nothing. If you downloaded any of *my* config packages to try and get them running on your system, anyway, they all came with their little readmes trying to explain the why and how of it all, and revision histories.

If you're worried there are several versions of anything, what can I say. I always tried to keep just the latest one of *my own* stuff and I will clean up again soon -- it's not my fault if archivists at Hobbes went missing for a month, then went back to work just at the right time.

As for the .WPI, it includes (a version of) my configs, but I didn't produce the archive, let alone upload it to Hobbes. If you are curious about why I published new configs in parallel to the WPI, it just so happens that the current developer forgot to tell me he was modifying my work, or was going to release it, or ask me if I had gone on with it for the last six years, which turns out I had. And alas, while my own configs still work flawlessly with the older FTEs, they need to undergo modifications to work with what is inside that WPI I knew nothing about. We are trying to work out the current situation, so I am confident there will be fewer 'packages' to confuse you in the future. Meanwhile, I decided I could still contribute in other positive ways, like trying to document a great program for the benefit of others.

Lars

  • Full Member
  • ***
  • Thank You
  • -Given: 0
  • -Receive: 21
  • Posts: 163
    • View Profile
Re: Manual for eFTE/2 / eFTE / FTE (Folding Text Editors)
« Reply #3 on: December 03, 2017, 10:33:05 pm »
1) Where is the latest version of nepmd ? What is the latest version of nepmd ?
2) Why is there no coordination in development of eFTE ? You appear in the netlabs eFTE "Direct Contributors to eFTE2" section. How come you don't know what has been going on in the last 6 years ? Why did you not add the documentation to the netlabs repo ?
3) Who is "I" or "they" in the description of eFTE on the "trac.netlabs.org/efte" page ?

For this reason I have been using EPM. Since EPM is lousy, I wrote myself two simple EPM REXX macros that allow me to indent and unindent text according to the tab settings and added keyboard shortcuts and menu entries for them.

Unfortunately there seems to be no coordinated effort in anything. Welcome to the Warpcave.

Lars


« Last Edit: December 03, 2017, 10:35:36 pm by Lars »

Alfredo Fernández Díaz

  • Newbie
  • *
  • Thank You
  • -Given: 0
  • -Receive: 4
  • Posts: 8
    • View Profile
Re: Manual for eFTE/2 / eFTE / FTE (Folding Text Editors)
« Reply #4 on: December 04, 2017, 01:32:12 pm »
I don't think lack of coordination is exclusive to the world of OS/2. I belong to several other 'circles', so to speak, and I see the same patterns/problems with people losing interest and retreating into their caves, then coming out into the daylight again, only to find the world has changed but never left a note for them... It just hits us harder because there are fewer of us and word of mouth doesn't spread anymore--you need to keep asking people about everything, which IS kind of backwards if you ask me.

Sure, a great many projects have suffered (and still suffer) from lack of coordination, but at least some of us are working to get something together again. Are you really interested in the details, or was it all rhetorical? Am I the only one who got forgotten and cut off when changes were made to Netlabs after years of inactivity? I kind of doubt that. Maybe I am the only one stupid enough to keep trying to come back.

Now I know I can commit stuff again, and so I will when I have more updates -- but until everything got finally cleared out I thought it might be better to publish what I had where I could, rather than keep it to myself and wait to get access again, or get hit by a truck meanwhile. Please excuse me if that bothered you.

Lars

  • Full Member
  • ***
  • Thank You
  • -Given: 0
  • -Receive: 21
  • Posts: 163
    • View Profile
Re: Manual for eFTE/2 / eFTE / FTE (Folding Text Editors)
« Reply #5 on: December 04, 2017, 02:32:29 pm »
Ok, first things first:
I sincerely hope you don't get run over by a truck. Not for a piece of SW anyway :-)

My questions were not meant as an insult. But I thought you had been working on eFTE all along.
And for eFTE, I can at least find it on Hobbes. For NEPMD, I can only find a very old version on Netlabs.
I know that Andreas Schnellbacher is working on NEPMD but I have no clue how he can be contacted or where to get the most recent version.

As to Netlabs: ok, I have been working on the USB repo for the last 7 years on a fairly regular basis. Maybe that is the reason why I would "pick up" all the proper transitions. But Adrian Gschwend has and will always be helpful to get you access to the SVN repo you need to work on. In particular if you already contributed in the past (let me know if you need his email address ...).
For you updated documentation, I'd put that in the eFTE repo right away. It's important that things don't get lost or spread all over the place in an uncontrolled fashion. Even if the documentation is not completely ready yet ...



Andreas Schnellbacher

  • Sr. Member
  • ****
  • Thank You
  • -Given: 1
  • -Receive: 15
  • Posts: 259
    • View Profile
Re: Manual for eFTE/2 / eFTE / FTE (Folding Text Editors)
« Reply #6 on: December 04, 2017, 05:48:39 pm »
I know that Andreas Schnellbacher is working on NEPMD but I have no clue how he can be contacted or where to get the most recent version.
He is reading what you're typing. ;-) A few days ago, I noticed that they've closed my old web site. The old test version 1.13 is not available anymore. I already have a plan where to go (also influenced by your posting here):
  • V. 2.00 will have updated docs.
  • V. 2.00 beta (1.19) will include everything except the updated docs.
  • V. 2.00 alpha (1.18) will be made available in a few weeks.
  • V. 1.17 can be obtained on request: prename dot lastname, followed by at, follwed by web dot de. It can also be compiled by yourself, if you have VAC 3.08 or C Set/2.
There are still a few things to do before spreading the current version, e.g. rename setting keys, move code, rename files. Note that a newer version always contains code to remove and change stuff from older versions. But I decided to to that first, before the first beta.

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Thank You
  • -Given: 255
  • -Receive: 49
  • Posts: 1708
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: Manual for eFTE/2 / eFTE / FTE (Folding Text Editors)
« Reply #7 on: December 04, 2017, 06:49:35 pm »
Hi Alfredo.

Thanks for posting your manual. Currently it is hard to find people that want to document OS/2 software. I will recommend you to upload the manual to Hobbes and the Internet Archive also.

It depends too much how you like to write the manual, but there is also the eFTE/2 Track wiki and the OS2World wiki where you can collaborate to also post some of your documentation.

I don't use eFTE/2 but I applaud your efforts on the platform.

Regards
Martin Iturbide
OS2World NewsMaster
... just share the dream.

Alfredo Fernández Díaz

  • Newbie
  • *
  • Thank You
  • -Given: 0
  • -Receive: 4
  • Posts: 8
    • View Profile
Re: Manual for eFTE/2 / eFTE / FTE (Folding Text Editors)
« Reply #8 on: December 04, 2017, 07:45:16 pm »
Hi, Martin, thank you. Now that I have access again, I will soon upload the manual to the main repository, either after some refactoring, or in its current form if I get no feedback within a reasonable amount of time. From my experience I thought I would have to wait a bit more to do it so I tried to make the interim productive.
-----
Lars, sorry if I got a bit overboard, I tried not to. Regarding NEPMD and Andreas, I think now you can ask him to publish both a new version *and* a valid, updated, visible contact address with it ;)

However, please note his words: "I noticed they've closed my old web site". Sounds familiar? It's not just Netlabs.

So far my activity has come mostly in bursts, but that's the way it is for most of us. The problem is, the fewer we are, the more that builds up with everybody else's discontinuities. I don't doubt Adrian may still be very helpful (last time we met was like 15 years ago), but what Netlabs really needs and lacks is some working self-sustaining infrastructure. Of course some admin has to know who you are before granting some privileges, of course site revamps are necessary from time to time, but it's entirely beyond any common sense that you need to get in touch with them every single time anything happens when you look away--It's not that I was cut off even from projects I managed (notably FAT32): in 2017 I can't even reset my own passwords TTBOMK. What if a project's admin goes away for a while? Or something really bad happens? Yet another discontinuity. Or a bunch of them. Or the final one: "Oh, I lost access to X/Y/Z. Again. F*ck it."

Over time I have came to limit the time fraction I will devote to chasing people around, so I can actually try and write stuff instead. Now that I can commit and publish properly again, tidying and cleaning up will come soon, rest assured, but given the current state of affairs I'm afraid that shrink-wrapping stuff will remain a second priority for quite a while.

Thanks for reading. Back to the manual? :)
« Last Edit: December 05, 2017, 06:55:09 pm by Alfredo Fernández Díaz »

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Thank You
  • -Given: 255
  • -Receive: 49
  • Posts: 1708
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: Manual for eFTE/2 / eFTE / FTE (Folding Text Editors)
« Reply #9 on: December 05, 2017, 04:44:21 pm »
Hi Alfredo.

What about a new logo (and in vector format) for the project inspired on the icon?

Regards
Martin Iturbide
OS2World NewsMaster
... just share the dream.

Alfredo Fernández Díaz

  • Newbie
  • *
  • Thank You
  • -Given: 0
  • -Receive: 4
  • Posts: 8
    • View Profile
Re: Manual for eFTE/2 / eFTE / FTE (Folding Text Editors)
« Reply #10 on: December 05, 2017, 06:40:33 pm »
Hello, Martín, I see you've been editing the project wiki. Why not, I'm not clear on where you want to use that besides the wiki page? but I'm open to the concept.

However, I personally favor losing the slash in the name altogether. It is implied in the new VIO icon I created (see attachment  #1), but that's not set in stone. If it depended on me alone, though, that would be as much as you would see of it again. It think it was historically a bad idea to have that in "OS/2", so why repeat the move.

Re: your svg, if it looks like the PNG it will fit more the PM version, I think, but I can't view it in SeaMonkey (shows a blank page). I always code SVGs by hand in eFTE2 so I don't know what's up with your code (see attachment #2, table-of-contents icon for the HTML manual, for a simple example that works here).

André Heldoorn

  • Full Member
  • ***
  • Thank You
  • -Given: 37
  • -Receive: 8
  • Posts: 235
    • View Profile
Re: Manual for eFTE/2 / eFTE / FTE (Folding Text Editors)
« Reply #11 on: December 05, 2017, 07:22:35 pm »
I will recommend you to upload the manual to Hobbes and the Internet Archive also.

</silence>
Preferably in one Hobbes archive (or two), at stated earlier. Users will have to study and/or use the WPI file, your two updates and some manual. If you want to attract users or to promote it being used, then a collection of archives isn't the best strategy.

Two packages are acceptable: an "official" WPI distribution and an "unofficial" single, clear add-on package. More than two isn't required: Young's and yours.
<silence>

Alfredo Fernández Díaz

  • Newbie
  • *
  • Thank You
  • -Given: 0
  • -Receive: 4
  • Posts: 8
    • View Profile
Re: Manual for eFTE/2 / eFTE / FTE (Folding Text Editors)
« Reply #12 on: December 05, 2017, 07:40:19 pm »
André, as I said, I'll be doing a cleanup of my own stuff soon, and now I'm sure we'll able to do the same at Netlabs. We should have less packages in the future than we have now, namely one current release, and *maybe* legacy FTEs --if they can't be removed from Hobbes--, but it will still take some time to unify, etc. I see the manual has been downloaded a number of times now, so please, don't post those anywhere else (Hobbes) unless I do get hit by a truck before we can proceed with the official release.