Prism: The documentation makes me want to die

[ronnieoverby]

I realize that my hyperbolic title seems distasteful at first, but hear me out.

The documentation found at http://prismlibrary.readthedocs.io reads like Moby Dick or War & Peace. It's a wall of text.

For the developer that just wants to know how to do something with Prism, a better reference with less exposition is sorely needed.

The WPF samples repository is actually very good at this, but a more traditional web based reference would be better.

[brianlagunas]

We accept PRs :)

[ronnieoverby]

I realize that. I'm not raising an issue like this to troll you or to ask you to just drop what you're doing and write me a set of docs that I enjoy.

I was hoping to start a discussion.

For some reason, the Caliburn Micro docs have this problem, too. Is there something in the water that makes MVVM authors want to write these tomes?

Also, I find the pluralsight course Intro to Prism or Prism Fundamentals or whatever it's called, to be better than the official docs. The issue with that of course is that it's behind a paywall and it's not specifically for Prism vToday, which always makes viewers feel like they might be wasting their time, though I know that the video course is largely compatible with the current version.

[dansiegel]

@ronnieoverby consider the title you chose or how you phrased your issue. Neither of them scream "I want to start a discussion".

[brianlagunas]

The current WPF docs were written by the Microsoft P&P team and just brought over. Docs are always the last thing an OSS author wants to do and are often the most neglected. I haven't touched the current docs, because although they are a tough read, all the information is there with very detailed explanations. So definitely not worth the time to rewrite docs.

[ronnieoverby]

@dansiegel it absolutely screams that. I was probing for senses of humor, finding only sand and bones.

@brianlagunas P&P; it all becomes so clear. I'd be happy to submit PR's of concise examples of things I've gleaned.

Also, did you know that the Read the docs site's search is broken. I've searched for phrases that I know are in the text, finding nothing.

[bartlannoeye]

The broken search is something RTD has to fix (https://github.com/rtfd/readthedocs.org/issues/1487), that's not our job.

[ronnieoverby]

Highly recommended episode of Herding Code:
http://herdingcode.com/herding-code-224-jeremy-miller-on-marten-postgres-and-alba/

On Tue, Jun 6, 2017 at 2:06 AM, Bart Lannoeye [e-mail]
wrote:

The broken search is something RTD has to fix (rtfd/readthedocs.org#1487
https://github.com/rtfd/readthedocs.org/issues/1487), that's not our
job.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/PrismLibrary/Prism/issues/1075#issuecomment-306391021,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAGKpGlBlAPr7uRe2epvSXBwz_cKnzxFks5sBOxmgaJpZM4Nwjlr
.

[brinko99]

@bartlannoeye It is your job to make the software usable, and that means documentation. Search on RTD has been broken for at least two years. Without search, documentation is useless. I'm currently deciding whether to use Prism on our new project; I've used it in the past and know the learning curve for new users. It's a shame to see that the already poor documentation has regressed (no/obsolete MSDN & CHM).

The link you point to also has a workaround that the Prism team could (apparently) easily apply and thus make RTD usable. It is suggested that Pandoc be used to convert the docs to RST which is natively supported by RTD.

[dansiegel]

@ronnieoverby there is plenty of humor around here. The way your issue comes across wasn't funny, and trust me I get in trouble by the P.C. police often for accidentally intentionally crossing the line with my jokes.

@brinko99 I've got to be honest with you, to blame Prism for RTD being broken is a total copout, and pretty stupid. I mean seriously, if that's your basis for deciding whether or not to use Prism, then you might as well not take advantage of any of the thousands of frameworks and toolkits that use RTD, including a lot of the .NET libraries from Microsoft. Certainly if you've got some input for how the docs could be improved to better help, that would be a discussion worth having. If you're trying to learn more about the framework and need help I think you'll be pleasantly surprised at how open and willing to help the Prism community is whether you file a bug on GitHub, ask a question on StackOverflow or even on the Prism Slack channels.

[brinko99]

@dansiegel I am saying only that it is in the interest of the Prism community to make it easy to learn. I don't mean to cast blame but indeed offer this feedback. RTD is simply the wrong tool for hosting mkdocs due to a crippling bug and lack of interest in fixing it (for most document sets RTD does work fine). It seems that RTD is not interested in fixing the issue as they see the workaround as requiring "at most an afternoon's worth of work".

As a result of their bug, Prism and its users suffer.

That all said, thank you and the rest of the team for putting together a great framework and working hard to interact with the community.

[dansiegel]

@brinko99 I appreciate the feedback that it this RTD bug is posing a problem for you. Unfortunately without an alternative being suggested, I'm not sure what we could do to fix the docs experience for you. Certainly RTD even in it's current state is better than what we had previously with just a bunch of markdown files that you could view on GitHub.

[ronnieoverby]

@dansiegel I guess you're right that my humor is objectively not funny. Sorry about that.

Isn't the RST conversion a suggested alternative?

Look! A discussion ensued. Imagine that.

All weapons of mass sarcasm laid down, I want to say that Prism is a good and helpful project. It's hard work maintaining OSS. It's harder work fielding issues on a popular open source project. But...

I don't like the knee jerk reaction of "We accept PR's"; closes issue

That is what decidedly doesn't "scream, ' I want to have a discussion'. " I think that is the total copout. Of course I want to have a discussion or I wouldn't have bothered.

So let's all let our defenses down. ::waits for retaliation::

[brinko99]

@dansiegel @ronnieoverby Right... might the workaround proposed by RTD of converting the mkdocs to RST format be considered? It seems that others have had success using Pandoc for this: (rtfd/readthedocs.org#1487)

[brianlagunas]

@ronnieoverby It wasn't a knee jerk. It was in response to a blatantly asinine issue being submitted. Your humor was not realized when responding. The RST conversion wasn't related to your original issue. Your original issue was about how hard of a read the docs were and you wanted a simpler version. So the discussion this is turning into does not even address your original pain point.

@brinko99 I hope when you re-read your initial statements you realize how ridiculous they are. You might have not meant for them to come off that way, but they did.

Regarding the RST conversion. This is not a priority. We are not going to spend the time to convert all our docs to another format just because RTD has a bug. If there are better free online documentation options available that support MK, please list them.

This is a freely open source project and is maintained by the community. No one has a job or any type of obligation to work on or support Prism. It is done by people with a passion for the project and they sacrifice their free time to do it. When people complain and initially come off as jerks (even if unintentionally), it puts everyone on defense and makes it less likely that we want to spend our free time helping you.

If I provided a paid support option, would that be of interest to you?

Here we are with this issue:

• I agree, the docs could be less wordy and more to the point (P&P is notorious for long-winded docs), but the fact of the matter is that the WPF docs that are there are very detailed and complete. If you would like to attempt to rewrite the docs and submit a PR, we would be willing to review the work you do and work with you to make sure everything is covered appropriately. This is not an effort I, or the rest of the current core maintainers are going to spend our time on.
• broken RTD search is not something we are going to claim responsibility for. While broken search sucks, you can still use the left nav and read through the wall of text or use the browsers "Find" feature.
• if there are other documentation options that support MK docs then please provide a list of options that could be investigated when we have the time.

One last note, if you want to complain about something or request improvements, a discussion is more likely to occur if you succinctly explain the problem and provide alternate possible solutions to that problem. Saying "this makes me want to die", or "it's your job so fix it" is not very conducive to a discussion.

[lock[bot]]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.