Picard Documentation Project

Long term planning then. This initiative is still quite a way from complete (whatever “complete” means). The other thing is that the script function documentation is actually pretty static, so it isn’t a huge amount of work to manually update the doc on those rare occasions that something changes. I think, if I really tried, I could come up with something to extract the current information from the source code docstrings, and then just reformat to rst and add to it.

No, no, no! I think the in-app documentation stuff is great. Please don’t even think about removing it.

I agree completely. I was just thinking that another advantage to pulling from a common source would be to minimize the translation effort required. No need to duplicate effort, especially since translators’ time and effort is golden.

3 Likes

@rdswift Thanks a lot for working on this. I very much like the approach to put the current technical documentation into such a format. It is much easier to extend and maintain overall, and I think this is good for both the users and the maintainers. A few thoughts from my side where we should go here:

  1. I like it very much how this documentation extend what we already have. Things like the introduction and the glossary are great.

  2. I think this should replace the relevant documentation on the current website. The website itself of course stays as the branded advertising and download page. IMHO we should replace the documentation links directly to the generated docs (and introduce redirects of existing URLs). I would keep the quick start guide as an introduction, but add a link to the full documentation there to dive deeper.

  3. Some parts need to be discussed, but I also would move the FAQ, the Troubleshooting and the Linix Flatpak install instructions.

  4. As @zas said above, we should take advantage of the ability to autogenerate the scripting documentation. We don’t need to do this immediately now and can do this later. But I think it would not be too difficult to have a script that generates https://github.com/rdswift/picard-docs/tree/master/source/functions . What we are currently missing here are the categories for functions, but we can add this to Picard as well.

1 Like

@Zas What do you think how we should host this? I think it would help us if we would host this on Github Pages and have a musicbrainz.org subdomain for it (picard-docs.musicbrainz.org or docs.picard.musicbrainz.org). That way we would have a stable URL and could move it at any time, but having it on GH Pages allows us to easily automate the deployment and keep the documentation up-to-date this way.

1 Like

There has been substantial progress on this project, with a few new sections added and some of the others expanded a bit. (The PDF is nearing 150 pages in length!) I still need to expand the glossary, tag and variable definitions, and add examples, but we’re slowly getting there.

I have a few specific requests at this point, if anyone can spare a few minutes:

  1. Please review the new Status Icons section to make sure that they are defined correctly?

  2. Please review the Plugin Options section to ensure that the icons and actions are correct?

  3. Please review the new Recommended Work Flows section to see that these work flows are actually the “best practices” and that I haven’t introduced some errors?

  4. Any suggestions of what should be included in the Examples section?

I’m getting to the point where I’m starting to miss things when I do a review, so another set of eyes going over it would be greatly appreciated. Thanks.

3 Likes

We can easily set up a musicbrainz.org subdomain, just tell me what you want. I’m fine with picard-docs.musicbrainz.org.

3 Likes

Thanks to @Zas, the documentation is now available from a stable URL under the musicbrainz.org domain, https://picard-docs.musicbrainz.org.

2 Likes

The Picard Documentation Project has just hit a major milestone… The system is now set up to support multiple languages. In order to test the upgrades, I’ve translated it all to French and that is now available as one of the choices in the options (or available directly by browsing to https://picard-docs.musicbrainz.org/fr/). I suspect that the translation is far from perfect because I don’t speak French and ended up doing everything by hand using Google Translate.

Now that the structure is there to support multiple languages, we’re looking for volunteers, both to help with the translations and/or to serve as leads for a language. The language lead would review all of the translations for their language and approve the translations before they are posted to the live site. We’re still sorting out the details of how this is all going to happen, so there is still a certain amount of flexibility at this point.

If you are interested in helping out, even if just identifying mistakes I’ve made in the French translation, please let us know and see the Contributing information in the project repository.

Thank-you all in advance for helping to make this better for all users.

6 Likes

Impressive work, again.

On a personal note, I do have some experience in translating software to my native language (Dutch), but I have found that the fellow countrymen that are computer-savvy and interested in this sort of software are usually comfortable using it in English, and don’t even switch it to Dutch.
(they must be a bit like me… )

So, that doesn’t make me volunteer to pick-up this big translation job.
(and, not the most important consideration, but translating is usually not a very thankful job that gets you much feedback or appreciation)

But… if another kaaskop decides to pick-up the challenge and start the task, and would appreciate some assistance, I’ll be there.

3 Likes