Please provide a structure to the documentation

Site Feedback
1

The documentation section seems to be structure-less: It seems to be a collection of assorted articles about random topics.

This is like opening a random page in a user guide and reading it. It does not build a true understanding in the reader’s mind!

It is essential to provide a structure to the documentation, so that the reader is guided through a step-by-step introduction to the software; and led through the topics with gradually increasing complexity.

In this, it is worth emulating books that provide alternative reading strategies. They have an introductory section at the beginning, to explain how to read the book.
Typically, it suggests different sequences of chapter numbers for different purposes.

A similar treatment should be provided in the Documentation section.

When a user contributes documentation of a new topic, it should be fitted in this framework. This can be done by either volunteers or the site admin.

That would enhance discoverability of the new article, and every reader will be able to fit the new information better in his mindmap.

Apart from sorting the articles chapter-wise, each article should also have a grading based on the skill level (beginner, intermediate, advanced). This allows a newbie to avoid getting bogged down in complex topics, while the veterans can skip the “beginner” level articles.

Without a structure, all types of readers won’t get what they want/need.

To sum up, what we need is-

  1. A TOC that provides a structured view of all topics
  2. A tag that shows the placement of each article in this TOC
  3. Another tag that shows the complexity level of the article
    (beginner, intermediate, advanced)
    If these tags can be color-coded, it will help instant recognition.
    (e.g. beginner-> green, intermediate-> yellow, advanced → orange)
  4. A “see also” section to cross-refer to other related articles
  5. Another section where videos on the topic are linked.
    (volunteers can keep updating these links.)
2

There is a loose structure through tags. And you can easily search within the documentation category and tags. Even search without confined to categories gives the documentation highest priority, Also, some topics do cross reference others.

Why don’t you go through all of the documentation topics and create the Table of Contents in a reply? Then I will add a page and paste it in there.

3

I was trying to make that point exactly!

  • A search is “pull” method, where the user knows what he wants to know.
  • On the other hand, a user’s guide is in “push” mode, where the reader is fed the knowledge in a particular sequence. That develops his mindmap neatly.

For example, the most basic question for a newbie is, what workflow should I follow?

  • The user may not be familiar with video editing at all. So he needs to know some alternative workflows.
  • The user may come from other video editor, in which case he has to unlearn some strategies and learn new tricks that are more efficient.

Thus, for any user, the question is, how/where to begin, and which Shotcut features will help me achieve maximum efficiency and best results.

The documentation does not fulfill these needs.

Secondly, although some articles provide cross-references and illustrations, many do not. This can be addressed by having a standard template that nudges the author to provide this information.

1 Like