Proposal for further documentation improvements

[mawe42]

Proposal

As the website is easier to update for us now and the API docs are cleaned up, I would really like to spend a little more time to clean up the rest of our documentation.

The points on the top of my list are:

1. Reduce the number of places where people can find documentation

We currently have documentation

• on the fluidsynth.org website,
• on the GitHub Wiki,
• in the generated API docs,
• in the source /doc directory (plain text, markdown, PDF, ...),
• the standalone fluidsettings.xml file
• and the man page.

I think that makes is quite hard to find information, and it's also a cause for a lot of duplication (sometimes with subtle differences) and makes it unclear where to add new documentation.

2. Better separation of information for different target audiences, topics and use-cases

Some of our documentation pages already make quite a good distinction between the different target audiences, but others give information for both (or all) of them. While that is probably not a huge problem for users of the API and library, it might be confusing for "end users" who simply want to use the fluidsynth executable and read references to API functions.

The same is true for larger topic areas and/or common use-cases, like compiling & installing, playing MIDI files, rendering MIDI to audio files, real-time MIDI input, tips for low-latency output, interactive commands via the shell, ... and so on. For most of these we already have some documentation, but again it's sometimes difficult to find or intermixed with other content.

3. Updating outdated content, (re)moving historical info

Some of the content in our Wiki and other places of documentation is outdated and need a face-lift.

There is also content that we have kept for historical purposes, like the "Historical Background" on the main README file. I definitely agree that crediting all the contributers to FluidSynth and especially the founders is extremely important, I think this information could be moved to a less prominent place.

Need for feedback

Now my first question to you is: Do you agree that the issues I raised above should be tackled?

And if you agree, then I would really like to discuss how I could approach this task. While the three points above look fairly distinct, I have a really hard time coming up with an idea on how to structure the work. It seems all very intermingled... before updating outdated docs, it would be great to consolidate them all into one place, to reduce the workload. And while updating and/or rewriting some of it, wouldn't it be easier to separate them for the different target audiences at the same time?

So currently my gut feeling is that it might be easiest to simply start from scratch. Write the main index page and structure the information into different areas and topics. Then fill that structure with content by copying existing docs and also writing new content at the same time. But before I even attempt this (probably very long) task, I think we would need to decide which documentation should live where. Especially with regard to the content in the /doc directory in the source tree.

If you want then I can mull it over myself and make a suggestion. But if any of you have a strong opinion on which docs should go where, that would be very helpful to hear beforehand, I think. And of course any other ideas or reservations you have about this proposal.

Cheers
Marcus

(P.S.: should this be discussed on the mailing-list instead or here?)

[derselbst]

(P.S.: should this be discussed on the mailing-list instead or here?)

Let's do it here, the list is pretty dead.

[derselbst]

FWIW, here's my feedback. Probably biased...

1.

• I don't think we (should) have documentation on fluidsynth.org, we only (should) have pointers there.
• The GitHub wiki is nice, because it's user editable. As such, it should contain mostly information for "normal" users, i.e. about fluidsynth itself and a bit about the technology behind it.
• API docs is for the geeks, ofc.
• For me, the /doc folder is the location where we develop the API docs (and the location for other fluidsynth-internal related docs). A normal user should not look there. That said, it would probably be a good idea to move out the polymono stuff to somewhere else - or at least provide links to it.
• The fluidsettings.xml file is part of the /doc folder, so I wouldn't count this extra.
• The man page is... well... a historic leftover for unix people who don't have a working internet connection, or so.

2.

Actually I think we're already making a good job on "information separation". I mean, we keep the user-related use-cases in the wiki and the geek stuff in the API docs. For me, those are the only places people should really be looking for information.

3.

Agreed. I'm open to moving and refurbishing content. I don't think it would be necessary to start from scratch though.

But, like I already said, I'm probably completely biased. It would be nice to hear some "normal" user about that. On the other hand, Marcus, if it fits into your current schedule and you already want to start, feel free to propose changes.

[mawe42]

Thanks Tom, that's helpful! And I agree, "starting from scratch" sounds very drastic. Maybe I gave the impression that I think our docs are currently bad or unhelpful. That's not what I meant to say. I think we have a lot of really useful documentation. But my impression is that with a new structure (and some cleanup), it could be made even more helpful and easier to digest, especially for newcomers.

Ok, so the /doc folder is our place for the API docs and documentation about the code itself (for people wanting to help improve FluidSynth). No documentation on the fluidsynth.org website, only links to documentation. All the rest goes into our Wiki. Sounds good to me.

I would like to propose larger structural changes to the information in the Wiki. And I would rather not edit the Wiki bit by bit and have all changes visible immediately, so simply editing pages doesn't really work. And GitHub doesn't support pull-requests for Wikis. So I guess the best way would be to fork the project wiki in my own GitHub account, make the changes there and ask for feedback and review. When or if we agree that the changes are worthwhile, we can simply update the FS Wiki repo from my fork. Does that sound like a good approach?

[derselbst]

So I guess the best way would be to fork the project wiki in my own GitHub account

Sounds like a good plan, go for it :)