Documentation rework

[sciurius]

Alyn Gwyndaf wrote:

Johan, I can take on a user documentation role. Can't really help with coding, but I do write professionally: not strictly technical writing, but mostly user training materials in design and technology fields, or making business topics clear and readable for non-specialists. English-only, I'm afraid.

[objectivesea]

Proper, well-organized documentation will be of great help for both new and existing users. I see it as proceeding from Chapter 1 — guidance for installation on Windows, Mac and Linux/UNIX; to Chapter 2 — a sort of "Hello World" example that is very basic but can immediately demonstrate the program's utility in generating a simple melody score or tablature. Subsequent chapters should each introduce one new feature and provide a worked example, showing the source code to be entered and the expected output.

While the rest of the book is being drafted, the first few chapters could be made available as a PDF file, along with a method for accepting suggestions for improvement, perhaps by making an editable Word or LibreOffice file available for download.

Once the English documentation is tested and found to be correct, to the point that people can follow the instructions and replicate the project examples, I would suggest that we need to make use of an easy interface such as Transifex or Wikitrans for translating the documentation into other major languages, like French, Spanish, German, Dutch, Esperanto, etc. People who are fluent in a non-English language, either native speakers or who have professional competence in that language, as well as possessing professional competence in English as a second or third language, would be ideal candidates for supervising a particular translation into their strongest language.

The English version will remain the basic source document, but the global translations will not need to wait until the canonical version is complete. After a few chapters are tested and complete, however, translators would be able to start their work. We would just need to assign version numbers and keep them consistent across languages. File naming conventions should also be established that incorporate the basic two-letter abbreviation, like IT for Italian or ZH for Chinese. Maybe Alyn, who modestly claimed only English skills, might also be able to work on the Welsh (CY) version when the time is ripe for that task.

I wish Alyn well, and I commend him for the most generous offer to facilitate the important ChordPro documentation project.

Kind regards, Erik Bjørn Pedersen ("Objectivesea" at WIkipedia and Tatoeba)

[gwyndaf]

Just scratching a few initial thoughts, based on what I've had to explain to other people when trying to describe ChordPro, or help them use it.

• Descriptive nature of the ChordPro format. Most people will likely be more familiar with modern wordprocessing, where there's no separation between content, structure/function and appearance. The idea of separating content/structure and styling remains a relatively modern design concept, so needs a little explaining. I've sometimes done that with a simple diagram that shows 'song' and 'styling' inputs to the software, and 'output'. Also explain merits of this approach (e.g. repurpose song content for different output and styling intents).
• Recognise that other software understands the ChordPro format. Not detailed, but simply enough to show how the format is intrinsically useful, because it's portable. This provides an opportunity to mention that the level of ChordPro support varies between software. It's outside scope to document compatibility level of other software, but maybe include/reference table of what features are supported by different releases of ChordPro. This potentially allows other software to more clearly identify its level of ChordPro support (e.g. v5).
• Language: the terms 'specification' and 'reference implementation' might be a bit technical or confusing, and terms like 'ChordPro format' and 'ChordPro software' might be clearer for general explanation.
• Software: it might make sense to give more/initial focus to the GUI, probably citing Windows examples, which is probably most common. However, this could potentially increase the user base reliant on the GUI, and thus create more demand for existing features to be available through the GUI, e.g. creating a songbook with filelist or clearer/simpler system font selection.
• Software focus or standard focus? Although the ChordPro format is the logical starting point, most of my conversations suggest that non-technical people tend to think of ChordPro as a software product. I suspect there might be a risk that people easily grasp the format, but then stumble when trying to install/run the software. So, for clarity, it might be more accessible to focus more on the software, and deal with the 'hard bit' first. That then lays the groundwork to then move progressively through simple to more advanced uses of the format and configuration/customisation.

Overall, I'd envisage something that's maybe more tutorial in nature, i.e. introducing concepts and practices roughly in the order they might be needed as a user progresses from basic to customised usage (rather than how they logically relate to ChordPro functionality). I'd see the core reader as someone who already understands musical concepts, is familiar with writing up songs on a wordprocessor, and is used to Windows or Mac based GUI software. Linux and CLI approaches still covered, but maybe not first.

Because 'tutorial' and 'reference' materials serve different purposes, this could exist alongside the existing documentation, which could continue to serve as a detailed reference, and be linked from tutorial. In the early stages, at least, that makes it possible to provide a clear grounding in using ChordPro, while still covering the full functionality in detail.

[gwyndaf]

@objectivesea Thanks for your thoughts, Erik. Although I am indeed Welsh, I grew up in England so my grasp of the language is very limited (but something I'm looking to improve).

I'd imagine that translation might be some way into the future but, for future-proofing, can you tell me if the translation interfaces you mention favour any particular document format?

Right now, I'm looking to choose a useful file format for outlining and drafting, which is clear and unobtrusive for writing, supports simple graphic illustrations and examples, is cross-platform and shareable for review/testing, provides a solid foundation for multiple output formats such as HTML and PDF with no additional reworking. And automated translation.

My background is more writing and communication than development, so I'm open to suggestions on a useful, well-established format. To get the work started, I'll most likely start with Markdown or LibreOffice Writer, which are more writing- than code-focused, and allow flexibility in repurposing the material later on.

[kh63894204]

Hi All,

I would like to offer my help with this documentation project in any way needed. I have quite a bit of technical writing experience for both tech level and general end-users. I'm located in New York and English is my primary language. I am retired now so I have all sorts of free time to offer.

I've been using ChordPro for the past 7 months to build up a song library for our local ukulele club. It was no small task for me to learn all the options and capabilities of this application. I agree that creating guided tutorials would be more helpful for the typical user.

Ken H.

[gwyndaf]

Thanks very much Ken. I haven't yet given much thought to how the work could be divided up, and might wait a while to see who's interested/available to help and suitable workflow. However, some initial thoughts...

I've been using ChordPro for about 5+ years, and the development of my knowledge has largely tracked the evolution of ChordPro, rather than the perspective of a user who's new to what's now fairly mature software/standards. So, your more recent learning experience will be very useful, to both inform the content/structure and review for clarity. I've had some experience of trying to explain/coach ChordPro to new users, and insights into the experience of recent new users will help identify the main knowledge/understanding gaps that need filling.

Right now, I wonder if you could perhaps reflect on the concepts or practicalities that were hardest to grasp when you were learning ChordPro, and maybe share those at some point, but no rush. For instance, you mention it was "no small task", so were there any particular obstacles that took most effort or tenacity to overcome?

[kh63894204]

Hi Alyn,

I was already well versed in the ChordPro format using another app for many years so I didn't have to learn any of that. However, I wanted something that would give me much more flexibility in the formatted output so that's when I looked into ChordPro.

Getting started using the basic ChordPro program was really straight forward. Even playing around with customizing the spacing, margins, fonts and sizes isn't too complicated. Learning to do really fancy formatting with Pango was a learning curve for me (mixing fonts and colors on the same line, strike-outs, rising, etc...). Also messing around with all the options in the config file to get the look that I liked took awhile. I also spent a good amount of time modifying the ukulele chord library to my liking. The wxchordpro.exe editor is also not feature-rich so it took me awhile to figure out a good work flow.

I think we could start out with making a top-level outline of the tutorial topics. From there, we could divvy up the parts to assign to different people for authoring.

Ken H.

[gwyndaf]

Thanks Ken. Yes, I think identifying and prioritising the intended readership (and thus tone, focus and learning journey), and outlining a suitable sequence of topics for them will be important early steps.

Your Pango comment is interesting. I suspect that people more accustomed to wordprocessors might be tempted to ask "How do I make ChordPro behave like Word?", which is a valid question, but one I'd be keen to reframe rather than answer directly. That is, it's a fundamentally different approach, which would make more sense to someone familiar with early semantic HTML. Suggesting that it's anything like a wordprocessor could cause confusion later on.

Pango would be a more direct answer to the "like Word" question, such as directly styling things like typeface, size, colour etc. However, that immediate gratification might be at the cost of fully understanding ChordPro's 'primary' features like directives and configuration. That is, it's not an efficient use of ChordPro to, say, put a whole chorus in bold by using Pango.

I'm thinking that the hierarchy/sequence in which to present ChordPro functionality might roughly reflect its evolution and refinement, e.g. from line-based to character-based formatting. My instinct is that Pango should be introduced later, and would then be useful groundwork for configuration options and designing a custom layout.

Another consideration (although it might conflict a little with the above) is to focus initially on what can be done through the GUI. 'Functional' features like transposition might be a bit more advanced than basic layout and formatting, but they also represent a good reason for favouring ChordPro over a wordprocessor, so covering them early would give even basic users some 'quick wins' for choosing ChordPro.

Incidentally, as you play ukulele, I've just updated my suite of ukulele chord definitions (C, G and D tunings), and the master file from which they're generated, if you'll find those useful: https://github.com/ChordPro/chordpro/issues/220#issuecomment-2221155191

[sciurius]

It is great to see you guys working together!

I'll try to stay out of the loop as much of possible, but there are some points that I want to address at this stage.

I'm a strong believer in version management. The documentation should therefore be written in, or can be converted --lossless!-- to, a textual format (e.g. markdown) that is under revision management (e.g. git). Also, it should be possible to produce a (section of a) web site from the textual format.

The current documentation is written in markdown and processed with hugo to create static web content. This doesn't need to stay that way if you have better alternatives.

Initial focus on the GUI is a good idea. You may want to use the (new) macOS GUI since that is much more powerful than the classic GUI.

As for chordpro markup (I no longer call it pango): this can be integrated in the GUI. You create bold and italic text and when saved this is turned into markup.

A big thank you to all of you!

[kh63894204]

Alyn and Johan,

I'm in agreement with your comments. I probably shouldn't have said that it took me awhile to learn ChordPro since the Pango styling stuff is not technically part of ChordPro. However, for me it was what I specifically wanted the app to do.

Once a person gets past the basic ChordPro configuration and usage, I think that output formatting and styling is the next thing that people will tackle. I see a fair amount of questions on the forums relating to this and that's where I usually got the answer to my own newbie questions. The (excellent) ChordPro reference documentation does contain all the necessary information but it's not in an easy to follow guided format.

In my opinion, I think that nowadays most people would like ChordPro to be like a word processor. I'm hoping that the Windows GUI (or a web front end) will receive some more development love. I usually don't use a Mac but I am very tempted load up a VM to try out that new GUI that was recently developed. A great GUI would have a big impact on the ChordPro user experience.

Thank you for the ukulele chord libraries. I will check them out. I haven't uploaded my chord diagram changes yet because I'm still checking all of my chord sheets through them.

Ken H.

[sciurius]

most people would like ChordPro to be like a word processor

True, as long as the underlying format allows being able to exchange the songs with just about everyone else.

I'm hoping that the Windows GUI (or a web front end) will receive some more development love.

Yes, it would be nice if someone stepped up, just like Nick did with the macOS GUI.

I do have a prototype chordpro server that runs in a docker and communicates via a basic web frontend. It quickly runs into problems since the server runs in a different environment as the user at the frontend (think config files, fonts, images, ...).

A number of years ago I attempted the HTML + CSS → PDF route but there were (and still are, AFAIK) no tools that can produce a decent PDF from HTML + CSS.

FYI. https://chordpro.org/dl/ChordPro-6.050_081.dmg

[gwyndaf]

Ken, I agree that formatting will be a key aim for most users, and the output can indeed look similar to a wordprocessor's. However, I think it would be a mistake to suggest that ChordPro functions like a WP, even if future GUI developments move it more in that direction: right now, the aim is to provide guidance for using ChordPro as it currently is. I'd like to equip the user not only to get the results they want (or understand why not), but also to do that with least effort for a song; otherwise they might as well use a WP.

I do believe that helping users grasp the conceptual model of any software is an important step in providing a solid knowledge foundation. For instance, I often have a conversation with designers, who conceive a design and approach in terms of how InDesign functions (page-by-page layout model); but they believe it can be easily translated into MS Word (continuous text flow model). That it, they assume both applications follow the same model, but they fundamentally don't, even though the ultimate result of both is to organise ink on a page (or PDF).

So, I certainly agree that it'll be useful to recognise that users might want similar output results to a wordprocessor, and that formatting will be a high priority for many. But, to help them get there, I think we need to clearly establish the (different) working model of ChordPro.

Although inexperienced WP users might simply dive in and format text manually, experienced users should already use and understand styles (Heading 1, Body Text etc), so they should readily grasp the ChordPro concept that we're describing the function of different elements, not simply their appearance, so that could be a useful foundation to build on - certainly as an underlying concept, even if the mechanics differ.

There's potentially a tension here between 'tutorial', 'reference' and 'FAQ' approaches. That is, the clearest order for introducing basic concepts and methods to a new user might not be the same as the logical organisation of reference material for an experienced user, or the task-oriented 'how do I...?' of an FAQ. All are valid and useful approaches, but I think the main need right now is to provide a way in (tutorial) for new users.

So, although formatting is one big topic from a wordprocessor perspective, I think it'll need introducing in progressive (and possibly non-contiguous) stages that reflect different aspects of ChordPro. For instance, some initial thoughts based on current ChordPro functioning and features:

• Song elements and structure (essential foundation)
• Formatting via GUI (selecting a 'template' config, although I haven't seen the new MacOS GUI options)
• Formatting via directives (line-based)
• Formatting via Pango (character-based)
• Formatting/layout via custom configuration (probably focus on PRP rather than JSON format)

Right now, we have the challenge that some tasks (like setting page margins) that are standard starting points for a WP user, require configuration editing in ChordPro, which I'd consider a more advanced topic, and quite alien for non-technical users more familiar with GUI wordprocessors.

One way around this, to provide quick wins for new users, could be to offer a more extensive gallery of preset layout designs (config files). That's not strictly documentation, but enhances usability by reducing the need for manual design/layout configuration.

[sciurius]

I agree that setting the mental model has priority. A ChordPro song is a text document (which may be stored as a file on disk, or on the net, or in a database, etc.) that is maintained using a text document editor. The ChordPro tool (embedded, or explicit) creates a formatted song document (PDF, which may be a file on disk, etc.). I recently realised that modern computer (ohone, tablet) users look down on text editors but have no problem deploying those tiny widgets in mail programs and social media tools -- which are no more (often less) than very simple text editors.

I think following "Formatting via GUI" there should be a section "Using the CLI".

Please avoid the term "pango". While the Pango Markup Language was an initial inspiration for the ChordPro in-line markup they have diversed in very incompatible ways.

The preferred config format is Really Relaxed JSON (RRJSON), which is more similar to PRP than to strict JSON. There's a tool to convert JSON and PRP config to RRJSON (it even adds comments!).

Writing documentation will inevitably lead to software changes (e.g. to resolve inconsistencies) so be prepared to run the development version from git.

[gwyndaf]

From a user guidance point of view, I'm inclined to adopt the perspective that text editors, plain text and CLI instructions might be unfamiliar and intimidating to people who've grown up using GUIs and more interactive tools. Not so much 'looking down' but more pragmatically recognising that there's a potential user base who don't even engage in the forum: I've noticed a few people leaving when it seems like discussion might have turned too technical for them.

On the hand, we also need to equip users to exploit the full power of ChordPro, which will need to tackle CLI and configuration at some point. I think my aim is to lead readers there in a manner that means they're sufficiently invested by then and don't get deterred at that point. That'll need a bit of thought to chart the most engaging and accessible journey for the target user.

Points noted about avoiding the term "Pango", preferring RRJSON config format (which I'll need to explore myself), and working to evolving git versions.

I think my next step is to take a little time out from discussion to do the preparatory conceptual work, like defining target audience, purpose and aims of documentation, and thus outline/ordering of topics, for which current discussion has been useful. It'll probably be more productive to write those up in a well-organised fashion, so there's something tangible around which to focus further discussion.

[kh63894204]

Alyn,

I think the audience, intent, and approach are important decisions that need to be made before diving into content production. I'm glad we're giving this a lot of thought.

You asked me what my experience was like as a new ChordPro user so I was just rattling off my thoughts. I am a fairly technical person so I'm probably not a typical new user. I do have a lot of experience simplifying subjects from a neophyte perspective. I've actually found it a little difficult to explain to someone why they would use ChordPro instead of a word processor. I'd like to entertain you with how I see a typical new ChordPro user:

Let's start by assuming that a person is interested in making a chord sheet. In all probability, they would simply jot something up using a word processor. As they progressively get more sophisticated, they want to add chord diagrams. That's when they would go searching the web for something to use. Let's say they find a website that generates chord diagrams and they cut-n-paste those into their word processor. All is good in the world.

As their experience making chord sheets progresses, they find adding chord diagrams to be a major pain. They also realize that sharing their chord sheet in a proprietary format is not ideal. Time for another web search. For the sake of brevity, let's just say they discover the ChordPro website.

I think a person reading the ChordPro home page doesn't really see any compelling reason for using the program. However, it's free so they download, install, and run it. Now what? This is the point at which you'll either lose someone quickly or they decide to try it out a bit. If they chose the later, they will quickly encounter a lot of unfamiliar techno jargon and a much different work flow from a word processor.

I believe that this is the point at which we are looking to provide some help.

Ken.

[kh63894204]

Johan,

Please excuse my use of the term "Pango". I do understand that it should be properly called the "ChordPro markup language".

Ken.

[sciurius]

Hi Ken,

No need to apologise, it was not a complaint. It is just that I want to tackle these misnomers as early as possible. And, not being a native english speaker, my remarks sometimes sound stronger than necessary. Sorry for that.

Finding the right descriptive terms for some ChordPro concepts is crucial to make sure we are all talking about the same things and to provide unambiguous information to the users.

For example, the term ChordPro is sometimes used to designate the file format, and sometimes to designate the program. I think ChordPro markup better covers the typical ChordPro directives, so we need another term for the in-line markup. Printing is used quite often, although nowadays the PDF documents are mostly viewed on screen instead of printed. Chord diagrams versus chord grids. A bigger problem is font, that is used for several font-related topics.

I hope we can work out a good set of terms to solve these ambiguities.

[sciurius]

Let's start by assuming that a person is interested in making a chord sheet. In all probability, they would simply jot something up using a word processor.

I think most ChordPro users start with a ChordPro document they got from some source.

[objectivesea]

Hi, Alyn,

I may have misled you about Transifex. I had thought that they had a free level for non-profit or open-source developers, but it looks like their minimum charge is now $120 a month, which seems excessive, even confiscatory, to me. (https://www.transifex.com/pricing/). And Wikitrans is an app specifically for translating the English-language Wikipedia to Danish and Esperanto, so my memory was off on that as well.

Transifex’s interface, as far as I remember it, divides material to be translated into individual sentences, and makes use of a translation memory so that similar phrases get translated in a similar and consistent way. That can be convenient, especially for interface translation, but the lack of this feature should not be an obstacle when tackling documentation.

(By the way, the file format is a «text-based portable object file («.PO»).There’s some information here: https://www.simultrans.com/blog/what-are-.po-files , and there are likely some freeware or shareware alternatives to Transifex.)

If we have a document, perhaps in LibreOffice Writer, that makes use of defined styles and applies them rigorously, a prospective translator can work in place and make sure the correct style is still selected. Or a translator who works in another word processor can paste translated text over the original text, making sure that pasted text is unformatted; then if a few words in a paragraph need to be bold or italics, these styles can be reapplied selectively and as needed after pasting in the translation.

If you choose to use Markdown, I think similar considerations might apply; the syntax seems simple, and the translator should just make sure that the formatting of the translated text matches the original English version.

If you devise something like a sample page or two of proposed documentation, I would be happy to work up an Esperanto version as a test of the translation process, so that we can see how smoothly the process goes and to suggest work-arounds if anything does not go smoothly for some reason.

Once the ChordPro application reaches a plateau where it’s relatively feature-complete, you’re happy with the GUI, things are running very smoothly, and you foresee no major changes for the nonce, it may be time to begin internationalizing the application by producing localized interfaces. This is the kind of task that programs like Transifex (and, hopefully, freeware alternatives) are ideal for.

Kind regards, Erik

On Jul 10, 2024, at 3:16 AM, gwyndaf @.***> wrote:

@objectivesea https://github.com/objectivesea Thanks for your thoughts, Erik. Although I am indeed Welsh, I grew up in England so my grasp of the language is very limited (but something I'm looking to improve).

I'd imagine that translation might be some way into the future but, for future-proofing, can you tell me if the translation interfaces you mention favour any particular document format?

Right now, I'm looking to choose a useful file format for outlining and drafting, which is clear and unobtrusive for writing, supports simple graphic illustrations and examples, is cross-platform and shareable for review/testing, provides a solid foundation for multiple output formats such as HTML and PDF with no additional reworking. And automated translation.

My background is more writing and communication than development, so I'm open to suggestions on a useful, well-established format. To get the work started, I'll most likely start with Markdown or LibreOffice Writer, which are more writing- than code-focused, and allow flexibility in repurposing the material later on.

—

[gwyndaf]

No problem, Erik. I don't see translation as a high priority at this early stage, and not something I have a background in. ChordPro format and software are English-based, so we can't (currently) offer users a wholly native-language experience. However, it's a useful consideration, which I'll incorporate into 'big picture' thinking and outline planning.

Right now, I think it's most useful simply to adopt a flexible working format that will be easily shareable and doesn't rule out translation or other repurposing at a later stage. Markdown seems the simplest option, certainly for structured text, probably with GraphViz or Mermaid for simple conceptual diagrams, SVG for more complex vector illustrations and PNG for raster graphic examples.

Once draft content in that format starts evolving and being shared (probably github for simplicity), I hope that should make it easy for you to grab a sample and test out its suitability for translation.

[Desbeers]

ChordPro, the application, is an editor. It is also a reference implementation and the first impression. So, what to show when you are opening a ChordPro file?

Do you expect plain text? Do you expect a PDF render of your song? Or side by side?

I wrote my own program long time ago to show me my songs. Rendered from ‘ChordPro’ markup. Chordpro is the musical version of markdown for me. Plain text, simple, readable as-is but made as beautiful as you want it to be.

So, if it is up to me, no ‘markup’ buttons in the editor. ChordPro is Markdown. Not a weakness; a strength!

In my -very opinionated opinion-, I do not like the first impression of the generated PDF when opening my first ‘chordpro’ file in the GUI. Most probably you found it somewhere and expecting something nice. I see an editor, can open a preview and see something I don’t like too much.

Well, I wrote the new macOS wrapper. Better, but for sure not great.

In my -again- opinion, documentation is nice for those who read it but the application sets the first impression. That is my focus.

When I open a ChordPro file I want to play a song.

[gwyndaf]

Thanks Nick. One of my main aims (as a writer/educator) is to equip a less tech-savvy user to feel more comfortable with using ChordPro as it currently is. I'm not a developer so - aside from raising issues and suggestions - there's not much I can do to advance the software's progress!

In terms of the overall user experience, ease of use will likely come from a blend of GUI design and guidance, although they may come to inform each other. Of course, the ideal is that the whole process becomes so intuitive that no guidance is needed, but I doubt we'll reach that point even with a lot of development effort for the GUI (my Mac usage is sporadic, so I haven't seen your wrapper yet, I'm afraid).

For example, the ChordPro format, of putting instructions within the document, will be a new and alien concept to users who've only ever known WYSIWYG wordprocessor and DTP software. Not hard to grasp, but does need explaining, because it's quite fundamental.

Another example: the core concept of separating content (ChordPro source) and styling (configs) is fairly specialised and will be a bit abstract for many. It'll be familiar to users with HTML/CSS experience, but not many others. I've known many users (with and without design backgrounds) who only think in terms of putting 'ink on the page'. I've even worked with professional designers who haven't grasped the idea or usefulness of styles (or style sheets).

Even without procedural guidance, there's some conceptual background that needs explaining to help users get oriented for using ChordPro, rather than get frustrated and put off using it. So, this work will complement any advances in the GUI that might come with time.

For now, I'm happy to write guidance for users, and won't be offended if it turns out that no-one needs to read it!

[Desbeers]

Thanks gwyndaf for your reply. I gave a lot of thought.

First of all, I’m a user of ChordPro, my format for many years, so, the format is obvious to me and sometimes I forgot I had to learn it as well.

Second, my wrapper looks nice, however, its only on pair now with the Linux and Windows wrapper. It does highlighting of the text as extra and makes its easier to preview, but fundamentally, it is the same.

That was my goal.

Now that it’s done, I don’t like the result.

I never really used the official ChordPro program with all its possibilities.

Playing guitar is what we want. We don’t want to fiddle with configuration files, strange markup, JSON files; we want to play the guitar and have a great songbook to help us!

So, besides good documentation, the basics should give you a pleasure to use ChordPro to play your songs.

Opening an existing ChordPro file should give you a beautiful rendition of the source that you can’t wait to play.

So, it should not show you a text editor. It should show you a song.

When you start a new song, show a guidance. When you edit a song, show help when you open the editor. The current documentation is written in markdown, and same as the ChordPro format, it can be shown however you like! On the website, obviously, but also inside the application.

I’m fiddling around with my macOS wrapper. My dev-version opens existing files just as a PDF preview with a button to edit it. A new song shows a welcome screen.

From a GUI programming point of view, it’s easy for me. From a user point of view; there is a lot to learn.

I want to make it a great ChordPro viewer, simple to use and easy for small modifications, but offer the advanced possibilities for those who want to tailor the resulting PDF to their own needs.

If it is up to me, the GUI will never be a WYSIWYG editor. That will abstract the strength of a plain-text format into just another implementation. ChordPro is plain text and you can use and read it however you like. Again, it is musical markdown. There are many markdown editors but the best ones are the ones who does not hide the source but guide you.

[Desbeers]

I want to add that the GUI for macOS, Linux and Windows should be reasonably on-pair. I can’t make the macOS wrapper super-fancy and leave the other platforms behind.

The GUI version will most probably give the first impression but the strength is at the command-line. Also something to think about...

[gwyndaf]

Thanks for your comments @Desbeers. As previously, these seem to relate more to the software and UI design, but this topic is about developing new documentation.

I totally agree that the overall user experience can be enhanced, and the need for documentation reduced, with product/UI design enhancements, so they are related. However, I'm an educator/facilitator/writer, not a software developer, so there's not much I can do about software development within the scope of the documentation work.

From a project management point of view, it's theoretically possible to wait for an enhanced GUI before starting on documentation, but my thinking is to start work based on the current UI. If and when they get enhanced, that should mean only a reduction in the guidance needed.

Perhaps you'd like to open a new issue for discussion of UI enhancements that might make ChordPro more easy and enjoyable to use?

I'll be happy to contribute thoughts to that topic. I'll need to use the GUI approach quite systematically (and with a novice's eye) for tutorial purposes, so might notice aspects that seem to need a lot of explanation, but could be addressed with small GUI changes.

[Desbeers]

Sorry for ‘highjacking` the subject; did it with my best intensions.

I will just follow this discussion and if I can do anything related to the GUI just let me know!

[Desbeers]

I don’t talk so fancy; I submit pull requests.

[gwyndaf]

No worries. I can't code anything that's worth pulling, so this is what I can do!

Thanks for the offer regarding the GUI. I'm sure thoughts will occur to me once I start thinking about how a novice user might try to approach ChordPro.

[sciurius]

The beta site has a new search facility. Please check it out. The old search was dysfunctional for a long time, apparently noone missed it :).

[gwyndaf]

Great news. I tried the old search once and found it non-functional, but pages (including beta) seem fairly well indexed on Google, so I've tended to search via that route.

A thought: does the new search log the search terms? If so, that data could provide useful insights into which topics users need most help with, which could help focus user guidance.

[gwyndaf]

I found the search box at the top of the navigation sidebar on the beta's implicit home page https://www.chordpro.org/beta/, and it seems to work nicely.

However, the search box (or any link to it) seems to be missing from navigation bars on other pages, including the explicit home page https://www.chordpro.org/beta/home/, and there's nothing on the navbar that directs back to the home page with the search box.

As a result, someone who's already reading part of the documentation doesn't seem to have any direct route to the search feature. I'm guessing it just needs the navbar with the search box to be replicated to other pages on the site.

[sciurius]

With 6.060 comes a new landing page and an improved search facility. Please let me know what you think.

[gwyndaf]

Landing page is looking great!

Some general thoughts:

1) Maybe add a simple 'Documentation' link to top right menu bar. Although the 'Getting Started' button leads there, that might be counter-intuitive for users who have already gotten started and need to check some usage syntax etc. 2) It'll be useful to consider positioning and target audience, which might determine how the information's organised. For instance, if the aim is to attract musicians who aren't necessarily technologists, tunings and diagrams might be a higher priority than, say, Unicode support. I've been thinking about something like a "Why ChordPro?" section in my initial outline for user documentation, so further thoughts will follow from that. 3) On a small/low-res laptop screen, the nice graphic occupies most of the screen, so even "Welcome to ChordPro" is nearly off the bottom of the screen. On a mobile phone, it fits perfectly, with the 'Get Started' button nicely at the bottom of the screen. But that might have the effect that people just click the button, and don't scroll through the remainder.

Just initial thoughts, and generally looking great, though.

Seems to be an issue with the Search result links leading to missing pages (404). I think it's this:

• {start_of_chorus} page URL is https://www.chordpro.org/chordpro/directives-env_chorus/
• Search result link is https://www.chordpro.org/directives-env_chorus/

So, it's maybe that the search links are pointing to the right page, but at the wrong level.

[sciurius]

Maybe add a simple 'Documentation' link to top right menu bar.

Done.

On a small/low-res laptop screen, the nice graphic occupies most of the screen, so even "Welcome to ChordPro" is nearly off the bottom of the screen

What resolution is that?

Seems to be an issue with the Search result links leading to missing pages

Fixed, at least for the time being. As a side result, beta site searches now also go to the stable pages. I need a better fix for that.

It'll be useful to consider positioning and target audience, which might determine how the information's organised.

Your thoughts are very welcome!

[gwyndaf]

What resolution is that?

1280x800, though I'll admit it's an old laptop.

Search results links working nicely now. I see I can still get straight to beta docs at https://www.chordpro.org/beta/ and will just avoid searching those, which hasn't become my standard practice yet!

[sciurius]

Searching in the beta docs is now also fixed.