Docu-Enhancements on V11.4: Homogenizazion and reordering

[hoppfrosch]

I've made several enhancements (esp. to get things more homogenized) on the documentation. One major other thing I made, was reordering the contents of "Basic_Help" to put the things together. This allows for example a more meaningful target when linking to things on this page (for example: all sections concerning paste mode are grouped together now ... so when linking to "Paste Mode" you will be directed to a section which has all features of paste mode represented comprehensively ....)

For more details on my changes see the commits itself ...

[aviaryan]

Hi @hoppfrosch , I highly appreciate your work on these pull requests and in improving the docs. This pull as usual adds to the integrity of the docs . Before merging it to mainstream, I want to sort out some problems I found in here.

• The theme is getting darker and denser - Docs should be less vibrant, not bright in colors and consistent to look at. I plan to remove the fancy green and yellow colors I have added for code blocks and emphasis. I am taking PMC's and AHK's docs as the idols.
  1. The bold/strong on [action mode], [paste mode] and all other modes is not needed. It looks too dark in density especially when they are links. The brackets around all modes is just sufficient and it should be consistent (as you have already done). [ Links: Preview of basic_help.html , screenshot ]
  2. Consider using only the white theme for kbd. There can be variants of white if possible.
• Independent features like Copying paths to Clipjump , one time stop and more are not under Action Mode and so same heading tag (the dark blue one) should be used for all of them.
• The Overview for action mode is not needed. I give the link to easy keys in the Action mode description area.

• I am not sure what this means. There is nothing below it.

  Clipjump offers two main graphical interfaces to customization:

Related : #36

[hoppfrosch]

Hi @aviaryan,

I highly appreciate your constructive criticism - therefore I know what your preferences are concerning the look-n-feel of the documentation.(No "But ...." here, as I'm really interested in constructive criticism )

Your answer partly answers my issue #25...

Now my more detailed response:

The bold/strong on [action mode], [paste mode] and all other modes is not needed....

That's what I also thought too .... I simply started to homogenize all the [XXX Mode] entries and as in the original documentation those "mode" entries were often printed in bold I made this the default formatting throughout the pages I worked on (without special intention). I used the <strong class="mild> selector all over - therefore it should be easy to reformat the documentation via simply modifiying the CSS in a first step. In a second step the <strong class="mild> could be removed finally (if we decide to have no special selector for modes)

Consider using only the white theme for kbd. There can be variants of white if possible.

As clipjump makes heavy use of keypresses, releasing keys while holding another pressed and tapping other keys, I think it's a good idea to offer a visual distinction between those different key actions/states. I don't care about the final design - but I personally would like to see whether a key has to pressed, has to be released, has to be hold to get an desired result ... Different shades of white might be a solution - as long as they are capable of being differentiated visually

Independent features like Copying paths to Clipjump , one time stop and more are not under Action Mode and so same heading tag (the dark blue one) should be used for all of them.

Not quite sure whether I agree or disagree. On the one hand, those "prominent" features should be represented prominently as you suggested. One the other hand: For example Copying Paths to Clipjump is accessed via Action Mode (Ctrl+Shift+A-> C) - why not document this feature under action mode? An advanced user would probably like to see all different actions offered by Action mode summarized on one place in documentation (at least I personally miss yet/missed such a place) - whereas a Newbie would likely be interested in an independent listing of all features...

The same is valid for Paste Mode: originally Paste Mode was referenced/mentioned in many places - without really be introduced properly ( to put it bluntly). Working on the documentation I thought: "Wow - paste mode is pretty coool - what else is possible with paste mode?" - and looked in vain for a comprehensive documentation of paste mode ... Therefore I started to work on the documentation

I tried to meet both groups (Newbies/advanced users) without changing the documentation too much ...

The Overview for action mode is not needed. I give the link to easy keys in the Action mode description area.

I disagree here - as an advanced user I would like to have a comprehensive documentation of Action Mode (at least I personally would like to see this ...) Why not group all action mode related features under action mode? Looking on the original "basic_help.html" it's a plain enumeration of different features, wildly mixing "Paste Mode"-accessed features with "Action-Mode"-accessed features - why not group them thematically? No answer needed here - but thats what I thought after (repetitive) reading this page ...

I think those ovierviews are missing in a few more places ... for example "Settings": all over the documentation serveral ways (Settings Editor, Settings.ini, ClipjumpCustom.ini ...) for configuration are mentioned. My first thoughts have been: "A lot of ways and places - how are they related? And those fancy IniEditor-plugin - what's this? What?? - no overview over Settings?" Overview pages, describing almost all features on a certain aspect are one of my mostly missed things in the current documentation ... ("ChannelsOrganizer - Channel Selector - Pit Channel - ... how do they relate?")

I plan to remove the fancy green and yellow colors I have added for code blocks and emphasis. I am taking PMC's and AHK's docs as the idols.

Haven't used it yet ....

Docs should be less vibrant, not bright in colors and consistent to look at.

Fully agree - my first steps are meant to get consistency. This includes using consistent css selectors for identical/related things (pressing key (kbd), releasing key (key class="inverse")...) . Having this, a lot of the work is already done - the main thing then is adapting the CSS, which determines the final look. On the other hand the style/formatting shouldn't be to simplistic (for example by simple use bold or italic only) - I personally prefer to be able to distinguish different things visually (for example http://www.macrocreator.com/docs/p3-Playback.html - Bold is used for "Important things" and "Buttons". I'm not quite sure whether I like this or not ... ;-)

I am not sure what this means. There is nothing below it.

Ooops - that shouldn't have been part of any commit (was just an rejected attempt of providing a comprehensive description of the different places where/how to edit configuration). Please ignore this ...

---

As you see, a lot of the changes are based on personal preferences or can be considered as intermediate changes (CSS-styles should not be considered as finally - more important is the consistent usage of css selectors). If I know your vision about the documentation (see also #25), I know what to do ...

[aviaryan]

the [strong class="mild] could be removed finally (if we decide to have no special selector for modes)

:+1: The strong should only be used when the thing is introduced for the first time. The time when you say "..This is called [Paste mode]".

Different shades of white might be a solution - as long as they are capable of being differentiated visually

You can use a black border for key_pressed. I did this and tested the results on IE and chrome. It looks nice ! Download @ http://pastebin.com/5P6jmWR4

An advanced user would probably like to see all different actions offered by Action mode summarized on one place in documentation (at least I personally miss yet/missed such a place) - whereas a Newbie would likely be interested in an independent listing of all features...

You can add the link to shortcuts page for Action Mode as "Different actions available in the Action Mode" in the Action mode description text. Won't this be sufficient ? On the other hand, features like "Copy file path to Clipjump" where added before Action mode and originally featured a system level shortcut for them to work. They were independent functions in the past and though now they have lost their default global shortcut, they are still independent and don't require Action mode to work.

The same is valid for Paste Mode: originally Paste Mode was referenced/mentioned in many places - without really be introduced properly ( to put it bluntly).

I am completely with your reorganization of paste mode. It is much better now.

I think those ovierviews are missing in a few more places ...

Sorry here, I think I don't understand why the term "Overview" has been used. For example, paste mode's overview is located at the end of paste mode documentation. It looks like a "Conclusion" or "related" section. Shouldn't overview be at the top and briefly describe what this thing does; just like "Introduction".

Haven't used it yet ....

Yes. This was for me. I have done that in the past.

I personally prefer to be able to distinguish different things visually (for example http://www.macrocreator.com/docs/p3-Playback.html - Bold is used for "Important things" and "Buttons". I'm not quite sure whether I like this or not ... ;-)

He could have used a background box for the buttons. But it should be light in color and should not halt the text-flow i.e. it should look more like text.

... ... I will updated you with more ideas ..

[aviaryan]

I edited the kbd.css. As kbda has been used for the release key, it should be equivalent to kbd.inverse New - http://pastebin.com/M1t7nbvA

[hoppfrosch]

Concerning visual representation of "XXX Mode" (Paste Mode ...): Do you think it's worth to replace all the overfluous <strong class="mild>-Selektors with a own <div class="mode"> to have a central posibility to change to CSS?

I edited the kbd.css. As kbda has been used for the release key, it should be equivalent to kbd.inverse

I already replaced all kbda occurences with kbd.inverse in one of my previous commits - I still have to integrate your new CSS.

You can add the link to shortcuts page for Action Mode as "Different actions available in the Action Mode" in the Action mode description text. Won't this be sufficient ?

On the other hand, features like "Copy file path to Clipjump" where added before Action mode and originally featured a system level shortcut for them to work. They were independent functions in the past and though now they have lost their default global shortcut, they are still independent and don't require Action mode to work.

This is the view of the developer and not of the user. Looking as a user, those features are accessible only via Action Mode (at the moment) - and therefore (at least in the users eye) part of the action mode. Having it presented as a own "concept" (something independent of Action Mode) I (as a User) would expect, that it is accessible with a global shortcut as well ... (and the documentation should contain something like this: "It is accessible via global shortcut XXXXXX and also via Action mode smart key yyyyy")

Sorry here, I think I don't understand why the term "Overview" has been used. For example, paste mode's overview is located at the end of paste mode documentation. It looks like a "Conclusion" or "related" section. Shouldn't overview be at the top and briefly describe what this thing does; just like "Introduction".

Let's change the wording ... what I meant is: if I introduce links for example for Action Mode - where should the anchor be? At the place where the concept is introduced initially (_basichelp.html) - or at a place, where a complete reference for the feature is located (shortcuts.html? - or a own "Auto Mode" page or a comprehensive "Auto Mode" Section within any other page?) The latter one is what I addressed with Overview-Page. As user I would expect at the link target a comprehensive introduction and (at least ) an overview of the features (or: a comprehensive description of all the features ...).

Personally I don't have to strong feelings about it, as I have worked heavily with the documentation and now know where to find things, but I'm trying to play advocatus diaboli to show what I think it maybe missing ...

[aviaryan]

@hoppfrosch Due to a major and rather silly bug found in v11.4 , I did some heavy work both on the bug-fix and the documentation. I added many more tags and classes to the css so that they can stylize different types of data present in the help system. I plan to update the docs with these tags. I have already complete most of the smaller files of the documentation and plan to release the next version only after I'm done. (It shouldn't take long, provided I am anxious) .. To avoid more merging, can you please wait before I release the next version.

[hoppfrosch]

OK - will stop my work until you release your next version. If you need help with updating the docs, contact me for some support.

[hoppfrosch]

Closed pull request since it seems to get obsolete through recent updates