Documentation complaints

Linc

This discussion was created from comments split from: [HQ news] Vanilla has a new R&D lead (spoilers: it's me).

peregrine

Documentation is definitely going to be a perennial focus going forward.

It seems like above statement is a perennial statement as well, if truth be told and not much change. Its not your fault your staff is lean, but maybe you could get some interns who are gung-ho or volunteers with interest and leeway.

this is meant to be constructive criticism even though it might not appear to be..

As far as other R & D how does it deal with add-on section and documentation.

My thoughts on why it may be so difficult for new users of open source vanilla....

couldn't find my old link that stated some of these concepts. (either it was deleted or I couldn't find it due to my inability to enter the proper search term).

the current documentation is difficult to navigate, and not as robust and complete as the old documentation. The entire layout is difficult. The phbb documentation layout (e.g. the faq) is so much easier for someone to navigate and find things without 10's of clicks. Even the old vanilla 2.0 documentation is easier to find things.

It is hard for new open-source vanilla users (incomplete, hard to navigate documentation).

Also hard for new users to find answers to questions, since many answers for locale definitions, config statements, etc, etc, were asked under the vanilla category, then a mass movement of discussions were moved into newly created vanilla 2.0 category even though they were not vanilla 2.0 specific but often related to vanilla 2.1. Then the vanilla 2.0 category was archived and probably 90% of the new users don't find the answers because if you don't click the archive box the answers are not found and don't appear in the search.

If the reply is "you" (plural you the community) can add or change the documentation, then that's the reason why.

We may have the desire, and maybe the inclination for change, but the credibility that things would get implemented is a bit strained and thus reduces even an attempt.

Same issue with the add-ons section under disrepair. plugins that don't work and should be archived. plugins that use code from 2.0 and will break other plugins.

Suggestions for add-ons section have been made for at least 3 years. Every year someone who hasn't found those old discussions (of which there are probably 5 extensive ones) comes up with the same suggestions and the same thing gets done (nothing). Even the simplest of changes can't be made because the thought that it must be totally overhauled results in a quagmire that prevents even minor helpful changes can be made.

Linc

@peregrine said:
It seems like above statement is a perennial statement as well, if truth be told and not much change.

There were 15 pull requests against docs in the last 30 days. There's been new theming documentation added and a complete overhaul of the SSO docs, including consolidating all existing docs to there from the blog. Even @Kasper chipped in to work on the underlying engine. Compare that with 8 for the entire first half of the year.

@peregrine said:
the current documentation is difficult to navigate, and not as robust and complete as the old documentation.

I completely disagree. Anything in the "old" documentation that wasn't saved was because it was simply wrong. And we've written far more docs since then.

@peregrine said:
It is hard for new open-source vanilla users (incomplete, hard to navigate documentation).

One of the pull requests reworked the left-side navigation styles to be much clearer. All the non-developers in the company praised the change and gave me feedback that it was much better to navigate now. If that isn't the case for you, I suggest filing an issue.

@peregrine said:
Suggestions for add-ons section have been made for at least 3 years

And yet I don't see anyone helping @hgtonight with his confidence rating feature.

@peregrine said:
Even the simplest of changes can't be made because the thought that it must be totally overhauled results in a quagmire that prevents even minor helpful changes can be made.

I don't recall saying it needed to be entirely overhauled. In fact, I think that's exactly the wrong approach. Simple changes are welcome and encouraged.

peregrine

@peregrine said:
Even the simplest of changes can't be made because the thought that it must be totally overhauled results in a quagmire that prevents even minor helpful changes can be made.

lincoln said: I don't recall saying it needed to be entirely overhauled. In fact, I think that's exactly the wrong approach. Simple changes are welcome and encouraged.

Simple change. create a new category Broken Plugins and Themes.

then have someone we can contact to move those Broken Plugins and Themes into that category.

if a plugin or theme does not work according to spec in vanilla 2.1 it should be moved to BROKEN (if the author hasn't fixed it by now, it should be moved to Broken until they do).

@peregrine said:
Also hard for new users to find answers to questions, since many answers for locale definitions, config statements, etc, etc, were asked under the vanilla category, then a mass movement of discussions were moved into newly created vanilla 2.0 category even though they were not vanilla 2.0 specific but often related to vanilla 2.1. Then the vanilla 2.0 category was archived and probably 90% of the new users don't find the answers because if you don't click the archive box the answers are not found and don't appear in the search.

maybe a moderator or volunteers with category changing abilties could change categories when they see a discussion is not 2.0 specific, if you don't want to change the search behavior. It certainly could aid new users to do either one of these.

Unfortunately I have a slow connection, so I can't even use your new documentation at all now. This is how it looks to me. I am basing my opinion when I could see a properly represented web page. but i can no longer see one.

lincoln said: There were 15 pull requests against docs in the last 30 days

for some reason I have never been impressed with numbers like these. I've never been impressed with number of lines of code changed either. I guess some stats make some people impressed and some people unimpressed.

lincoln said: I completely disagree. Anything in the "old" documentation that wasn't saved was because it was simply wrong. And we've written far more docs since then.

I guess we will have to completely disagree. I completely disagree with you on this subject. Its your choice to do what you want. I am providing my opinion, and I think it is much harder to navigate and not as complete as the old documentation.

Also confusing to have cloud stuff commingled with open-source stuff leading to ambiguity.
Commingling the cloud documentation (that doesn't correlate) with the open source and vice-versa is fairly confusing to new users when they see a feature and don't realize it is only for the cloud and vice-versa.

Maybe if you are really interested in seeing what the community thinks - you should have a poll that excludes staff employees, "other volunteer workers" (e.g. moderators), and vanilla marketers. That asks

was the old documentation easier to navigate.
is it easy to find info in current documentation
it it more robust and does it have as complete a documentation as the old documentation.
is it as easy to find answers to simple questions as other forum software documentation.
etc, etc.
also how does it compare to the wiki - does the wiki have alot of useful info that could be incorporated into documentation.
a question to community - what's missing in the poll would be good as well.

And if you do decide to have a poll and get honest feedback from the community, be prepared to allocate some time or resources to change it, if that is your desire.

still think a topic on use of caching when writing plugins would be a good addition, routines, procedures, etc.
also a topic on memcached (or is it memcache)
improving perfomance when using vanilla open-source
and frequently asked questions.

peregrine

errors when viewing docs page.

GET main.f8c00115.css

404 Not Found

docs.vanillaforums.com

270 B

23.235.47.133:80

430ms
GET search.b5f04b79.json

404 Not Found

docs.vanillaforums.com

270 B

23.235.47.133:80

590ms
GET css?family=Source+Sans+P...,600&subset=latin,latin

200 OK

fonts.googleapis.com

540 B

74.125.129.95:80

375ms
GET search.b5f04b79.json

404 Not Found

docs.vanillaforums.com

Linc

@peregrine Clear your browser cache for that site.

Linc

Simple change. create a new category Broken Plugins and Themes. then have someone we can contact to move those Broken Plugins and Themes into that category.

Feel free to send me plugins for deletion.

Unfortunately I have a slow connection, so I can't even use your new documentation at all now.

One of the changes should allow the documentation to work offline.