Documentation clean up

[ghost]

Revised on 2016.03.27

Documentation clean up is an ongoing effort and expected to finish soon (completed 2016.03.27).

Note to myself: Don't explain much in Wiki! Just explain in simple way, enough for users to follow. Steps should work and can be reproduced by anyone.

---

Clean up status ok : satisfactory -- : onhold x : deprecated %%% : messy

! Each of these articles (Definition, Rebranding, Remastering) should contain featured content navigation like Wikipedia, which links to all three articles (except the currently viewing article shall be bolded and unlink), which will promote discovery and encourage reading (done on 2016.03.21).

Wiki
ok Sidebar
& ok Home
ok Archive --- now simplified; since mentions are already documented by date (from top: newest to oldest); Separation by releases are redundant after all (why I didn't notice this earlier)?
x Changes log
ok Choosing Python over Gambas
ok Common mistakes
ok Contribute
x Credits
! ok Definition
ok Developer notes --- now legacy (probably won't get updated anymore)
ok Different images
ok FAQ
& ok Features --- now with optional screenshots (explain well in text, enhanced by screenshots);

There is no accurate guide for UI elements in documentation. Known suggestions below:

• don't use ` (grave accent) for other than codes and command line
  • good: sudo apt-get update
  • bad: Application > Internet > Firefox
  • alternative: Application > Internet > Firefox
• don't use <kbd> for UI elements, use "this" or this instead;
  • good: Ctrl+Enter
  • bad: Close button
  • alternative: "Close" button, Close button, «Close» button (rationale at below)
• then again, don't overuse formatting to indicate different UI elements i.e. tabs, buttons, labels;
• such elements shall continue to use text;
  • no format: Main tab, Open button, FileSystem directory
• and perhaps highlight the label of element;
  • format 1: "Main" tab, "Open" button, "FileSystem" directory
  • format 2: Main tab, Open button, FileSystem directory
• alternative formatting by using Unicode 1.1 characters:
  • symbol 1: ［Main］tab, ［Open］button, ［FileSystem］directory (U+FF3B, U+FF3D)
  • symbol 2: «Main» tab, «Open» button, «FileSystem» directory (U+00AB, U+00BB)
  • symbol 3: »Main« tab, »Open« button, »FileSystem« directory (variant of symbol 2)
  • symbol 4: ⌜Main⌟ tab, ⌜Open⌟ button, ⌜FileSystem⌟ directory (U+231C, U+231F)
• even with Unicode 1.1 characters (supposedly the most compatible characters), some mobile system doesn't fully support certain characters i.e. symbol 4 and shows rectangle boxes instead
• using "quote" or bold is likely less suitable than using special characters of Unicode, except for convenience and faster to type
  • the "quotes" are usually used to bring a string of words together to explain something
  • the bold is like italics to give emphasis to certain keywords in general
  • the UI elements are not just "string of words" or keywords, but also the keys to user interactions for using a program that runs on computer
  • «Close» button is likely more meaningful, instead of "Close" button or Close button (this is suggested for use on GitHub Wiki; However, "quotes" or bold would be more convenient and faster to type for generic use)
• using «double brackets» (a.k.a guillemets, a type of quotation marks rather than brackets) are likely good choice for three reasons:
  1. effectively distinguish label text from description text (known usage: to indicate "field" in word processor or e-mail markings);
  2. legible even without spacing;
  3. promotes continuity when reading on screen
     • continuous: «first» tab, «second» button, «last» directory
     • distractive: ［first］tab,［second］button,［last］directory
• the UI navigation is another headache:
  • symbol 1: Application > Internet > Firefox (U+003E, misleading use yet generic)
  • symbol 2: Application : Internet : Firefox (U+003A, alternative)
  • symbol 3: Application → Internet → Firefox (U+2192, used similarly in Xubuntu manual except emphasized by _bolded italics_ and the arrows may be styled using fonts and CSS, which cannot be achieved using Markdown)
  • symbol 4: Application » Internet » Firefox (U+00BB, reuse from earlier examples)
  • symbol 5: Application ‣ Internet ‣ Firefox (U+2023, like breadcrumb used in modern Windows, Ubuntu manual also uses this)
• while the symbol 3 and 4 may be common, these would look very small and your eyes need to squint (when viewing from desktop, but legible from mobile); symbol 2 is uncommon in my reading experience
• so remaining symbol 1 and 5; If possible, I'd pick symbol 5 (of course, symbol 1 would be more convenient and faster to type) but symbol 5 has few variations:
  • this type: ‣ U+2023 BLACK RIGHT-POINTING SMALL TRIANGLE
  • this type: ▸ U+25B8 TRIANGULAR BULLET
  • this type: ▶ U+25B6 BLACK RIGHT-POINTING TRIANGLE
  • this type: ► U+25BA BLACK RIGHT-POINTING POINTER
• even available since Unicode 1.1, none of these variations are supported properly on mobile platform; Then symbol 1, 3, or 4 would actually qualifies for best compatibility.
• apparently some symbols are rendered different in size or style, due to font preferred by the web page and not that is specified by web browser;
• then, symbol 3 → is likely good choice and logically means "if...then"; So this is preferred for Wiki and probably user guide also

ok First guide --- now concise and short enough already

• reduced text from 85 to 52 lines; this compare revisions
• but later increased to 54 lines due to minor revision to text order; last compare revisions
• linked to "FAQ", in case user in doubt
• linked to "Feature" page, on how to configure and use Customizer

ok Help for 14.04
ok Installation
ok Issue submission -- now at simplest; Keep good examples as guideline.
ok Logos -- quoted in issue 115
ok Manuals
ok Minimalist ISO
! ok Rebranding -- now ease of reading for either impatient users or curious users

! ok Remastering

• some contents from "First guide" will be moved to here
• this will be my third and the last article to be written for this project (done on 2016.03.26)

ok Screenshots &
ok Supported host systems
ok Supported images
ok Tutorials -- no changes in order, simplified headings

Repository
ok Customizer: Master branch (limited to documentation related files i.e. Contributors, README.md)

• Contributors: check recent contributors, which are missing from the list (done on 2016.03.26)
• README.md: to mention CLI doesn't take arguments after the option (questioned long time ago);
• or should this be mentioned elsewhere in Wiki instead (yes, mentioned in "First guide")

x CustomizerMedia

• Copied and renamed most files & to Dropbox storage
• This "CustomizerMedia" repository will be deleted permanently (done on 2016.02.05)

ok Dropbox

• this has been a shared location to keep copies of backup for Customizer releases and early documentation i.e. user guide 3.x;
• bandwidth limit allowed per month by Dropbox is basically 10x more than GitHub (should be more than enough to handle user visits).

---

Original thread

Some important things to clarify beforehand:

1. is gambas3 branch still relevant?
   • if no, I plan to remove from Wiki main page and move to Archive page
2. for master branch, which install method is recommended (or which order):
   • using old script (assume usable after I edit dependencies to suit version 4.1)
   • manual make (via README.md)
   • git clone (via FAQ)
3. for master branch, which launch method is recommended (or which order):
   • pkexec via Terminal/GUI
   • sudo via Terminal/GUI
   • gksu,kdesu,kdesudo via Terminal/GUI

Any other comment to improve documentation is welcomed.

[fluxer]

Hi,

1. Well, for me it is not. But it may be usefull to someone else in a sense that it has more features than master right now. I also keep it for historical reasons and reference on how to implement the extra features later into current master, or at least that was the plan.

From what I can tell people better not use it, the master branch has accumulated some fixes and changes that were required to support the newer Ubuntu releases thus I recommend moving on and remove the docs for it.

2. I would recommend building deb package and installing that so the package manager of the distribution (assuming Debian/Ubuntu/other apt-derived distribution) can keep track of Customizer's files.

But after all, most people do not want to deal with this and will just use the method from the README, which is the most obvious one. FAQ is fine too. Your call.

3. Ultimately, they do the same thing.

pkexec comes from Polkit/PolicyKit (I'm still confused about that project's name, reference to it varies) should be the most secure one since it is two layer security - first it has it's own set of policy rules and then it makes use of dbus which is also a security layer. It is recommended for GUI users but not always present on the system thus they can use gksu, kdesu, kdesudo, again, if they are available on the system.

sudo should be used only by CLI lovers, it also has its own policy configuration but is not ment for interaction with fancy (or not so) dialog boxes with input fields and such. It would be either a preference or necessity to use it due to lack of the mentioned priviledge esalators above. Sadly, it will not work as the user expects when used from .desktop file, an example:

• user installs Customizer with the following command: make ELEVATOR=sudo && sudo make install
• user tries to launch Customizer from menu
• user menu/screen/whatever freezes because sudo requires CLI interaction, it's stdin/stdout are on the TTY

I've seen polkit do the same when no agent is present so all in all - there isn't a perfect answer here. Stick with pkexec.

Cheers!

[ghost]

@fluxer
This is a follow up from question 2.

If users choose to install master branch manually (via README or FAQ), is it possible to safely remove all installation files i.e. without using package manager?

I have seen many instructions to install, but not otherwise (Ah, I suppose I can refer to your install script file as reference).

Could it be that 'manually remove installation' of any program on Linux is not advisable in general?

Sent using a Sony Ericsson mobile phone

[fluxer]

@clearkimura

Yes, it is possible to remove it. All you have to do is call sudo make uninstall from the source directory of the same version you installed from. If you for an example call uninstall from newer version it may no longer install old files that previous one did and the rule to remove it may not be present anymore. It's not like manual remove is a bad thing, it's just that you need to be aware of how things works, that includes the software you are going to remove (it's build system) and the system you are going to do this on. That is why package managers exists.

I hope this answers your concirns.

[fluxer]

@clearkimura
Well, you can create .deb package for Customizer:

wget https://github.com/clearkimura/Customizer/archive/master.tar.gz
tar zxvf master.tar.gz
cd Customizer-master
make deb

And then install that with dpkg -i <path to the .deb file>.

Cheers!

NOTE This method is most proper. The common practice to create package is without using sudo according to this Wiki.

[ghost]

The "Customizer User Feedback (2015)" has been finalized and the responses have been reset to a new sheet. The new form is now accessible from GitHub Wiki Home page.

[fluxer]

Nice, thanks.

[ghost]

Customizer wiki on GitHub now uses a custom sidebar for eased navigation. More changes may be noticed in stages to organize the contents.

Also, I have created a new repo to keep some resources (mainly screenshots) for the Wiki. Because of this, I finally learned to use git for adding images to Wiki by linking to images in repository.

I thought this is better than linking from external location, especially for lightweight files. Less the hassles to update on GitHub Wiki.

Edit: Removed link from "a new repo" text.

[fluxer]

Awesome! I did not even know that you can link images from repos :).

[ghost]

The 3.x user guide PDF and HTML files have been pushed to CustomizerMedia repo. Each can be downloaded to local machine via raw links (direct link will not work), which are used in Manuals page. Tested from recent Firefox Web browser.

[ghost]

Brought back old content "Minimalist ISO" in Tutorials page. The content is revised edition of original, which means deprecated information has been removed and some has been updated.

[fluxer]

👍

[ghost]

The First guide page now includes updated instructions to install, run and configure Customizer from master branch. Alternative installation methods, including gambas3 branch, are covered in Installation page as separate (which can be linked from the First guide page as well).

Some contents in the First guide are still in progress and will be updated later.

[ghost]

I won't go as far as making an official developer guide for Customizer, since I am more toward a documentation contributor and less than a developer.

So I decided to collate notes instead. Now accessible from the sidebar.

[fluxer]

@clearkimura

I've added some of the things that made me work on 4.x to the page, it's not history but if I'm to write the whole thing it would take quite a lot of time because there is almost a year between 3.x and 4.x release and a lot of things have happened during that period - something I do not have the time for. I hope that helps.

[ghost]

The First guide is more or less complete. But some linked pages from there might be updated later. The "Linux remastering help" section is now much readable in the Tutorials page.

[ghost]

Updated FAQ and other related pages to satisfy issue #107 and similar questions in future.

[ghost]

As today, I think I have fixed most of the mess that had been done on Wiki.

The most important piece, First guide is now concise and short enough to be read. Most text and links were moved to FAQ for better discovery and further reading. Features now includes useful screenshots, which makes it a good alternative to the user guide 4.x.

Since this issue was opened in late January 2015, the documentation clean up continued for at least a year to this date. And I have finally finished it. Whew.

This issue is now closed for good.

P.S.: I will review the entire Wiki for one last time, to check if I had missed anything else and do minor editing if necessary. I shall do so by end of this month (within next few days).