Key issues to be addressed with documentation

@willrossiter you might be interested in adding your opinions here :)

Just remember @gabornovoszadi this proposal currently running refers simply to a restructure of the existing content as the first piece of work we should carry out on the documentation. New content and more examples would come later.

As I say, I spent a bunch of time talking to various groups and pulled together the common themes. The good first move (of many including better content) I believe to be IA.

Key issue being, we need subject matter experts to write this stuff, in it's current state I don't know how motivated our community developer champs would be to get stuck in and contribute a decent block of technical doc content if newer end-consumers of that content cannot find things. Your well written content would get lost among the rest of "all the things".

Cleaning the mess will take several steps, this current proposal refers simply to taking the first step and that being make the structure better and more logical (please tell me the difference between reference, topic and misc?).

Then let's tackle improved content and example code, you putting your hand up to write some docs? The community is going to need us to pull together and create a valuable knowledge-base if we want to grow and innovate. No single community member know absolutely everything, that's the beauty of socially stored knowledge and communities.

Don't get me wrong, I'm not saying to keep the current IA and I'm not saying better IA isn't a step towards improvement.

I just think that addressing the IA of bad docs doesn't address the bad docs themselves.

Really, it all needs an overhaul with new IA and new docs. A new IA alone will just allow visitors to more easily search for docs that don't exist.

How do I use framework alone? How does the CLI behave compare to web interface? How use entwine in the CMS? Who knows, it's not ever addressed in the docs and an IA won't change that.

An important question is how do you define an IA for docs that don't exist? IA and design should follow content, not the other way round.

I'm happy to write docs and the current structure does hinder the writing of docs because they are topic based and not code based, but if there's no

Fundamentally the docs need to be written by core devs, by the authors. Anyone else is just interpreting the purpose of the code and how they use it, rather than the intention.

There's a lack of respect and effort put into docs and this is proven by the fact I've been on IRC and had SS staff tell me there aren't docs because no one would read them even if there were... I maintain: Addressing IA won't fix the root problem

I agree, it is but one step in a larger strategic intent of sorting the docs. There is no quick fix for this therefore I need to take a structured approach and get things in alignment so that contributing docs is less of a chore. @willrossiter and I will be doing some communications around this soon, keep it locked :)

"I’m happy to write docs and the current structure does hinder the writing of docs because they are topic based and not code based"

• I think this is what people mean when they say let's get the IA right first. The second step (writing more content) is critical but right now the IA slows that process down. We gotta sharpen our axe before chopping down the forest.

Thanks for that offer @edlinklater I may take you up on it :)

“I’m happy to write docs and the current structure does hinder the writing of docs because they are topic based and not code based”

Yes, there is a contradiction there, but my point is that I think it should be done in one go, rather than organising existing docs into an IA that either won't suit a new approach or an IA that will be mostly empty.

I'm happy to be the "tenth man" on this (ie: the guy who disagrees so that there's so actual debate on the issue)

@edlinklater is right, broken links are a big problem in the docs doo

@danielhensby if everything is priority, then nothing is.

I'm basing this critical path update to docs from discussions I have had throughout the community and feedback I have been collating.

Perhaps when I say "do the IA first", perhaps this could be done on a public beta site version of the docs (not the current main one) which we iterate on until we have:

1) IA in an agreed structure
2) Suitable content to roll with

This does however mean, more replication of stuff so I personally would like to see that beta site get to live asap and then get to work improving content and examples.

I don't think docs actually has an end point... it will keep evolving so I'm keen to work out processes to help that happen and to find ways for technical writers to be able to contribute with less barriers.

As I say, @willrossiter and I will have some more ideas and communications around this shortly, then ya'll are welcome to give us some feedback and get cracking on some more docs. Would be great to form a small project group around the docs actually if you are interested?

Thanks also for playing tenth man, it is in the discourse that we are able to innovate :)

if everything is priority, then nothing is.

true

I think the process of deciding the IA and the focus of the docs should be as public as possible

The rest sounds good :)

Two of the biggest pain points:
1.) When you search for SS solutions on Google, you'll often get old 2.4 results (and clicking "3.0" or "3.1" from there often leads to a 404). Also related, completely irrelevant 2.4 results from old blogs are often ranked too high. (SSBits anyone?) SEO MUST be considered in the Information Architecture. Make old documentation difficult to access and ALWAYS have a path from old doc to new doc (e.g. "You're looking at documentation for SS 2.4 Template Caching, click here for SS 9.2 Template Caching.")

2.) Documents do not have the absolute beginner in mind -- even those who don't understand Object Oriented code. Part of the doc's job is to explain modern code practices that they may not have been aware of while developing for other systems like WordPress. (Or at least link to documents that do.)

I would like to make a suggested for the documentation based on this google forums thread https://groups.google.com/forum/#!topic/silverstripe-dev/wJvUBrQV248

To improve the documentation related to the silverstripe template engine. To more clearly specify what the capabilities are including custom folder structures and the way to use the render with method.

I found the information on permissions, groups, security to be very limited. We need more: examples, description on how to works, easier to read documentation - in this area.

I agree with your 1st point @nathanjbrauer, having SS 2.4 come up in the results is fairly annoying. I think perhaps having a robots.txt file that limits search engines to only index the trunk documents (though still allow us to navigate to older versions via the doc website).

Thanks guys, note the current thing up for discussion in this thread is that we first start by dealing with the IA. @schippie I appreciate and note that you have posted about this particular point in many channels. It's on my radar. As it is a new request for documentation I'd appreciate it if you posted this via UserVoice, same goes for you @nicolaas :)

@shaundegreeff I actually have a WAMP screencast in the works, need to get time to narrate :) Also just updated the WAMP installation and getting started using composer or via package if you check the docs.

@camfindlay1 Thanks.. I checked it out. It looks good
The composer installation info for Wamp is under the doc called "Windows Wamp".

I recommend maybe adding a link to there from the doc called "Composer"...i attached a pdf with screenshots for clarification.

Thanks @shaundegreeff I agree a cross link would be good. Actually feel free to submit a pull request and add that link to the docs (good to learn how to do that if you haven't already done so). :)

@camfindlay1 I submitted the pull request