Discussion regarding Structuring of Desktop Documentation
First tasks are to:
- Agree on a precise definition and structure for Basic Usage, Advanced Usage, Reference Documentation, and FAQs, such that:
- Basic and Advanced Usage sections are user stories (answering "How To" problems)
- There is minimum overlap between the sections (i.e, same information isn't placed in two of them).
- To define a structure/format for Modules Documentation.
- To start working on the missing pages of documentation (especially in the Advanced Usage section).
While we discuss about the structure for the above mentioned points, we can work on the following side-by-side:
- Contribution guidelines for taking screenshots (Building over the guidelines for Android) to ensure:
- Consistency (Specifying preferences, height and width of the window, resolution, perhaps fonts/color of text/boxes/arrows).
- Legality (Referencing a list of interesting public domain and creative commons media files).
Guidelines:
- When making "How To" for specific problems, we should give a link to reference documentation for different kinds of options (by modules/by use case).
- There should be no (or as minimum as possible) redundancy in the documentation.
Key takeaways from the first meeting:
- The Basic Usage of the VLC Media Player is broadly in two uses - as a basic media player and as a media center (like controlling playlists).
- Most of the things we can do by the GUI Menu bar usually falls under basic usage.
- The content of Basic Usage is okay for now, we need to work on the structure (some addition and removing certain parts which are more suited for Mobile Documentation).
- (I don't remember this one properly, please correct if I'm wrong) Transcoding, and Services like Screens, Network, Discovery, etc. fall under the Advanced Usage section.
I think those were the major topics we discussed upon. Is there anything important that I missed?
End questions
The question I was meaning to ask towards the end of the meeting was this - suppose someone wants to add a logo to a file. One way to do this is using the GUI Effects and Filters (which is very simple), another is by using --video-filer
from the CLI (a user with minimal CLI experience can do it), and yet another way is to transcode the file while using sfilter=logo
(for this, the user might need to know which mux is compatible with which codec).
If we define the difference between Basic and Advanced Usage in terms of how much the user needs to know when trying to implement a feature, then I feel that maybe the first two methods fit the Basic Usage category while the last one should be part of the Advanced Usage section.
In such case, where there are multiple methods for achieving similar things, how should we categorize:
- Make a single file (as all methods are to achieve a common end result) and place it under the Advanced section because transcoding is mostly a part of the Advanced Usage.
- Break it into two files - one for basic usage and another for advanced (with both the files referencing each other).
Also, as Simon had mentioned, someone had made a draft structure for the advanced usage section. If it's public domain, can I take a look over it as it might be a good starting point?