Wanted: Volunteers to Update the Sigil User's Guide

[KevinH]

Hi evilmrb,

Thank you for your efforts.

Unfortunately, the work to update the user's guide seem to have gotten out of sync a bit.

Doitsu has already done a major overhaul and updating of the User's Guide and we are waiting for Hitch to proofread and edit it before making it official.

The latest version can be found here:

https://www.mobileread.com/forums/sho...7&postcount=23

Also ... IMHO, the building on Linux docs really should not be part of a User's Guide as they are so system/distribution specific and change so often and really are not something a User should worry about given the recent number of distributions that now include Sigil as a distribution package.

So please check out the latest version of the User's guide and rebase your improvement efforts onto that version less the building on linux pieces.

Thanks,

KevinH

[DiapDealer]

I agree with Kevin. The Linux building Instructions should not be included as part of the Sigil User Guide. Neither should the instructions for building Sigil on OSX or Windows.

[DiapDealer]

Originally Posted by Doitsu

@Diapdealer: Could you please create a user guide sticky so that volunteers can easily find the most recent version?

Which version of the guide should the sticky be pointing to? The one in Kevin's previous post? Or something else? I don't want to accidentally add to the confusion.

You hit me with a link to a post with the attachment you want people to start from, and I'll sticky it. But that may lead to heavy maintenance -- making sure incorporated changes get added for new volunteers start from.

Until the guides files are in a repo, I think it makes more sense for one (or maybe two people including Hitch) to be making the changes rather than a crowd pointing out fixes that may or may not already have been made.

I appreciate all the recent input, but we may run into a "Too many Cooks" situation if we're not careful.

I'd love to see a markdown representation of the chapters in a repo, myself. That way there'd be no need to worry about html, css, attribute orders, or opf/nxc stuff at all. Pull requests could be submitted by users and a behind-the-scenes process for creating the actual epub could handle the rest.

I could convert the "latest" chapters to markdown and put them in a sigil-ebook/manual repo pretty quickly if people think it would make sense (collaboratively speaking). From there, we could create an epub (as well as an online manual) pretty easily.

[xingenter]

Originally Posted by DiapDealer

I agree with Kevin. The Linux building Instructions should not be included as part of the Sigil User Guide. Neither should the instructions for building Sigil on OSX or Windows.

I respect your opinions and completely DIS-agree with both of you. Even if the build instructions are not included in the Sigil docs I think they should be somewhere and in a better format than those linked to from the Sigil home page, IMHO.

I didn't add build instructions for OSX or Windows because they are not needed - their users are catered for, Linux users are not.
My view is that the distinction between users and coders is blurred for Linux users because the assumption is that Linux users are comfortable compiling code - some may be, many won't.

If you look at the competition, Jutoh provides installers for Windows, Mac OS, .deb and rpm packages in 32-bit & 64-bit versions and the developer is a one-man outfit. Surely you must see that Sigil's developers are far better placed to create Linux installers than the average Linux user.

I am still using version 0.8.6 on Linux Mint (which I think was from a deb package created by your good self ). I would love to be able to upgrade to 0.9.7 but I'm not a technical user (although more so than a layperson I suspect).

Meanwhile I will still use (and love) my old version of Sigil, as well as Jutoh and calibre for my formatting endeavours. I hope you will consider my thoughts and be a bit more open to helping Linux users more.

Mark B

[xingenter]

Originally Posted by KevinH

Hi evilmrb,

Thank you for your efforts.

Unfortunately, the work to update the user's guide seem to have gotten out of sync a bit.

Doitsu has already done a major overhaul and updating of the User's Guide and we are waiting for Hitch to proofread and edit it before making it official.

The latest version can be found here:

https://www.mobileread.com/forums/sho...7&postcount=23

Also ... IMHO, the building on Linux docs really should not be part of a User's Guide as they are so system/distribution specific and change so often and really are not something a User should worry about given the recent number of distributions that now include Sigil as a distribution package.

So please check out the latest version of the User's guide and rebase your improvement efforts onto that version less the building on linux pieces.

Thanks,

KevinH

Thanks for the reply, Kevin.

You are right about the sync thing. It would make more sense for Doitsu to add my trivial updates to his sizeable ones, so I won't update anything.

Please see my replies to their respective posts too for a fuller picture.

Best regards,
Mark B

[Doitsu]

Originally Posted by DiapDealer

Which version of the guide should the sticky be pointing to? The one in Kevin's previous post? Or something else? I don't want to accidentally add to the confusion.

The one in Kevin's post. I.e. this one.

Originally Posted by DiapDealer

I could convert the "latest" chapters to markdown and put them in a sigil-ebook/manual repo pretty quickly if people think it would make sense (collaboratively speaking). From there, we could create an epub (as well as an online manual) pretty easily.

That's a good idea, but you'll have to make my changes permanent. (Currently outdated content and new contents is marked with two different styles. Both styles need to be removed and outdated content permanently removed.)
However, with the right regex, it'll take you only a minute to this.

It also couldn't hurt to briefly mention the new icon size option in preferences.html. (I attached a placeholder screenshot that you can use.)

[xingenter]

Originally Posted by Doitsu

Unfortunately, you didn't use my updated version to implement your changes. Can you please grab my updated version and re-implement your changes?

Also while you're at it could you please add the regex corrections suggested by CalibUser in this post?

Thanks!

@Diapdealer: Could you please create a user guide sticky so that volunteers can easily find the most recent version?

I hadn't realised there was a later version and that you'd made extensive changes. With that in mind, I don't intend to edit anything but you are welcome to include the changes I made if you wish.

It might be an idea to have a read of the posts I made to Diapdealer and KevinH for a more complete picture.

Hope that helps a bit.

Mark B

[DiapDealer]

Originally Posted by evilmrb

I respect your opinions and completely DIS-agree with both of you. Even if the build instructions are not included in the Sigil docs I think they should be somewhere and in a better format than those linked to from the Sigil home page, IMHO.

They're in the source code's doc folder (in both the markdown and html formats), and easily readable from the github repository (or on a local machine).

Not sure how including the instructions in an epub would be putting them in a "better format."

They're already written in html with links to the various subsections (or in Markdown easily viewable on Github). How would putting them in an epub make them any more accessible to users trying to build on Linux (pros or neophytes)?

We'll just have to agree to disagree, I guess. I thank you for you input just the same, though.

[Hitch]

Originally Posted by KevinH

Hi evilmrb,

Thank you for your efforts.

Unfortunately, the work to update the user's guide seem to have gotten out of sync a bit.

Doitsu has already done a major overhaul and updating of the User's Guide and we are waiting for Hitch to proofread and edit it before making it official.

The latest version can be found here:

https://www.mobileread.com/forums/sho...7&postcount=23

Also ... IMHO, the building on Linux docs really should not be part of a User's Guide as they are so system/distribution specific and change so often and really are not something a User should worry about given the recent number of distributions that now include Sigil as a distribution package.

So please check out the latest version of the User's guide and rebase your improvement efforts onto that version less the building on linux pieces.

Thanks,

KevinH

Kevin:

Wow, sometimes, the world turns so that you don't have to ask questions--oddly enough, I was just getting ready to confirm that this was the latest, before I started proofing. Synchronicity is a wonderful thing.

TY, I'm starting the first real pass (text only, first) on this today.

(waves at Diap)

Hitch

[Hitch]

Speaking of, @Diap, @Kevin:

How do you two want my tweaks, changes, etc., marked up? Right now, I'm making changes as I see them, and adding a line of comment, beneath, (in ePUB format, obv.) to indicate what I've changed. If you already have a change/comment protocol, can you point me to it?

Hitch

[KevinH]

Please just change the original and save it as a copy. I will diff your final version against the original and we can edit that diff to back out any changes although I doubt that will be needed.

Once you are satisfied, your version will become the basis for import into a repository to track changes, etc.

Thanks!

KevinH

[Hitch]

Originally Posted by KevinH

Please just change the original and save it as a copy. I will diff your final version against the original and we can edit that diff to back out any changes although I doubt that will be needed.

Once you are satisfied, your version will become the basis for import into a repository to track changes, etc.

Thanks!

KevinH

GMTA, as we say in my shop. (Great Minds Think Alike). That's how I'd already proceeded.

Can you two lovelies tell me, is there any specific section, for the users, that you feel needs real propping up, in terms of text/instructions/screenshots? If you don't know, off the top of your head, don't give it a moment's thought, I'm sure I'll see it when I get there.

Hitch

[BetterRed]

Whilst using the manual I've occasionally stumbled on instances where To do [whatever] click the [whatever] button is not augmented by or select the menu item [whatever] or its keyboard shortcut.

I don't have any tool bars displayed so there are no buttons to click, I can usually guess where the menu item is, but sometimes not.

I'm pretty sure I have also seen instances where explicit keyboard shortcuts are mentioned - F7 comes to mind. Given most keyboard shortcuts are user configurable this seems wrong to me, the keyboard shortcuts have names, so why not use them.

I also find the manual both verbose and imprecise, a common shortfall in documents of this ilk. Apart from the authors and copy editors, people don't read manuals as one might read a newspaper or a novel, they refer to them to get instruction on how to do something. Here's an example, of what's there and what I suggest is a better alternative



BR

[Hitch]

Originally Posted by BetterRed

Whilst using the manual I've occasionally stumbled on instances where To do [whatever] click the [whatever] button is not augmented by or select the menu item [whatever] or its keyboard shortcut.

I don't have any tool bars displayed so there are no buttons to click, I can usually guess where the menu item is, but sometimes not.

I'm pretty sure I have also seen instances where explicit keyboard shortcuts are mentioned - F7 comes to mind. Given most keyboard shortcuts are user configurable this seems wrong to me, the keyboard shortcuts have names, so why not use them.

I also find the manual both verbose and imprecise, a common shortfall in documents of this ilk. Apart from the authors and copy editors, people don't read manuals as one might read a newspaper or a novel, they refer to them to get instruction on how to do something. Here's an example, of what's there and what I suggest is a better alternative



BR

Hey, Red:

I'm sure that everyone, myself included, would eagerly welcome any other contributions/comments/criticisms that you'd care to make. If you'd like to send me some, I'll happily incorporate them if you don't have time to do that yourself, with attribution, of course.

Hitch

[BetterRed]

Originally Posted by Hitch

Hey, Red:

I'm sure that everyone, myself included, would eagerly welcome any other contributions/comments/criticisms that you'd care to make. If you'd like to send me some, I'll happily incorporate them if you don't have time to do that yourself, with attribution, of course.

Hitch

Hitch, my criticisms would for the most part be stylistic. I'm not sure the major stake holders, or average user, would appreciate my preference for a terse, impersonal, almost legalistic, expository form.

When your version is published, I'll 'edit' a section and post it here and let them pass judgement. Depending on the outcome we can discuss - I'd definitely need someone to proofread. As you've probably noticed I tend to omit and repeat words and sometimes whole phrases

BR

PS : Seasons Greetz, Happy New Year, and All That Jazz.

Were you one of the 1 billion our Lord Mayor said would be watching our fireworks, or do I regard that as a Post-Truth faradiddle, a bit of Fake News braggadocio, or an Alt+→ conspiracy Ψ²