Hook documentation changes in progress

Site Feedback (About the Forum and documentation)
1

FYI, overnight ( c. 2020-07-02 03:00 PT) we changed the underlying implementation of Hook’s Help pages . We used to use ‘weDocs’. As a result / concomitantly

  • the navigation sidebar is no longer present (but we are adding new navigation links)
  • the search tool is no longer present on the help page (stay tuned for more info on search tool, but till then a web search engine is your friend. You can use this parameter in most web search engines to constrain your search to Hook’s documentation pages site:hookproductivity.com/help/ (See Google’s help pages for more parameters).

Rationale for the change

We were not happy with several limits of weDocs, such as that weDocs:

  • insisted (before the latest update) that that every ‘weDocs’ help page appear in the weDocs navigation pane. That made the help-pages navigation pane too long. That forced us to store some of our documentation in a “help2” section, which is awkward for all (e.g., makes searching more complex).
  • imposes maintenance requirements (everytime it’s updated we need to match their updates, some of which introduced issues).
  • introduced several bugs in its latest revision. For instance, padding is gone. It no longer accepted Markdown for any page that we edited, which forced us to export locally to HTML and paste that in, which was tedious and not pretty. I assume there were workarounds, but we had had enough of the limitations/issues.

result

  • Removing weDocs means the help pages no longer have a table of contents side-bar.
  • The web pages all have (or should have) the same URLs as they did before, meaning your old links to the documentation pages (including those that you see in Hook itself), should remain valid.

Work in progress

We’re now gradually adding custom navigation elements back into the documentation section.
We will also migrate some of the “help2” content into the main help pages. In place of the /help2 section, we will use redirects and/or links so that the old URLs remain useful.

Around the corner

We expect to release Hook 2.0 this summer. That will call for substantial additions to the documentation, to explain the new features.

We also need to add more screenshots and screencasts to our documentation pages.

There are a lot of useful functions in Hook that aren’t yet widely known, partly due to the need for more/better documentation. We gradually update our documentation.

How Hook helped us migrate from weDocs to standard WordPress pages

Our help pages are written in markdown. Rather than rely on WordPress editor and wedocs versioning etc, we write the documentation source in markdown and store local official copies of all our help pages in a version control system. We use Hook to link each VCS (version control system) page to the public URL and to its WordPress edit page.

This means that each one of us here who is involved in documentation can write the page in the editor of their choice. We can do diffs etc. with the VCS. And of course navigation between the files and the pages in the browser is a synch.

All this makes it a lot easier to migrate away from wedocs.

See also Keep Track of What You Write on the Web – Hook.

2

FYI, we have indeed updated a lot Hook’s online documentation since I started this topic 2 weeks ago.
You’ll find table of contents elements on the main page, in each section, and at the bottom of each page.
There’s also a lot of substantial changes — too many to list here. I hope it helps :blush: .