Key issues to be addressed with documentation
Cam Findlay
Public
Seen by 47
Ok, I'm opening up the dialog around this - I'm interested to gain some deeper insight as to what the thoughts are around the SilverStripe documentation currently at http://doc.silverstripe.org.
I raised this in the IRC channel today with some good constructive feedback and will be collating everything over the next few weeks to see if we can come up with a good plan to move forward and improve documentation around the open source project.
What's currently good or bad in our docs? any other project docs you've seen that are amazing (and what makes them so)? Is there anything completely left-field we are missing?
Poll Created Mon 14 Jul 2014 1:21AM
We should improve the navigation/structure of the documentation first. Closed Fri 25 Jul 2014 5:10AM
Looks like the decision is overwhelmingly positive and we are going to go ahead with the IA improvements. @willrossiter and @camfindlay1 will look to have some more information around this shortly.
Key issue has been people finding doc material hard to find, suggest we first re-structure the docs site before dealing with re-writes and new content.
Results
| Results | Option | % of points | Voters | |
|---|---|---|---|---|
|
|
Agree | 86.7% | 13 |
|
| Abstain | 6.7% | 1 |
|
|
| Disagree | 6.7% | 1 |
|
|
| Block | 0.0% | 0 | ||
| Undecided | 0% | 23 |
|
15 of 38 people have participated (39%)
Cam Findlay
Mon 14 Jul 2014 5:51AM
From collection and grouping of qualitative data from IRC, dev list and discussions this seems to be a clear area of action we can take to gain some traction on the docs improvements. I see this as 1 link on a longer chain of ongoing enhancements.
Richard Rudy
Fri 18 Jul 2014 3:49AM
I find the examples when provided are often not well broken down. It's fine once you're familiar with SS but it can be a nightmare for beginners
Gábor Novoszádi
Fri 18 Jul 2014 6:20AM
New video tutorials with WAMP/MAMP examples, basic usage of Composer, config with YAML, etc? Anything necessary to introduce important concepts should be part of a tutorial series. Lynda's tutorials are good ones, often help me a lot to get started.
Daniel Hensby
Fri 18 Jul 2014 6:14PM
in reality the problem with the docs is the docs. No matter how well structured they are, if the docs aren't good, then they won't get better by being in a nice IA
Sam Minnée
Sun 20 Jul 2014 10:45PM
Although a new IA is pointless without more content, we should refresh the IA to make it easier to get more content in there.
Ed Linklater
Mon 21 Jul 2014 1:08AM
I think it's important to make current links still work, as we still get people in IRC with docuwiki links wondering why they don't work. Am happy to get involved in doing manual rewrites to make this happen.
Fred Condo
Mon 21 Jul 2014 6:31PM
Getting the IA right will make it easier to find existing docs & improve them. It will also help make it obvious where there are lacunae that need to be filled with new docs.
Shaun De Greeff
Wed 23 Jul 2014 7:12AM
When looking at videos and docs...please keep the windows guys in mind. Saw cast on using composer which was only done on Mac.
Cam Findlay · Mon 14 Jul 2014 1:20AM
This is a first grouping of feedback into some common themes and how many times other have made mention (it could probably be further refined which is what I'll end up doing before putting together a more concrete plan to get stuff fixed.
COMMON THEMES
IA/Structure/Getting around
Division of framework and CMS related docs +1
Main navigation makes it difficult to explore/discover content +2.
Current structure confusion - Misc, Reference, Topics unsure difference between (remembering where things are to return later is problematic) +4.
Search often used because it is hard to remember where things are in the nav +1.
Collapsed nav makes it hard to scan through all of what is available (results in jumping between sections, fix might be to show 2nd hierarchy of nav by default). Ideally some sort of overview/sitemap.
More meaningful naming for sections and articles.
Improved categorisation of articles into use cases rather than technical focus +1.
Monolithic navigation vs search (if the search is really good)?
Sometimes a google search works better than using the provided nav/search +1.
Problems knowing what keywords to use to get content.
No feedback in UI to know whcih version of SilverStripe the document is for(2.4/3.0/3.1).
A book style strcutre
Content Areas Lacking
Simply some areas are undocumented/incompleteness +2.
A roadmap of SS development +1
Testing
Framework only documentation +2
Routing
Custom Controllers
More examples/recipes/how things are implemented +8
More detail in articles (what is an appropriate level of detail?)
Some docs need rewriting by subject matter experts eg. injector.
Functionality
Critique of examples/improvements/use gists for examples.
Tag relevant forum posts, modules, blog posts along with docs (related community content).
API doc references for classes and methods used in doc articles.
Improved search relevance +1.
Searchable tag cloud build by community tagging (folksonomy) (logged in users tag with a term that makes sense to them).
Commenting under docs if they include examples/code discussion.
Processes
Review of external code examples, curated selection of the best ones (who does this?).
Examples of other docs people like
Code Igniter/Expression Engine http://ellislab.com/codeigniter/user-guide/ +1
PHP Manual has good usage examples +2
Laravel http://laravel.com/docs +1
Craft https://buildwithcraft.com/docs/introduction
Ruby on Rails http://guides.rubyonrails.org
Adobe ActionScript documentation
CakePHP http://book.cakephp.org/2.0/en/index.html
Issues
Some issues using docs with IE 9 and 10.
If we re-organised the docs, how do we deal with all the rewrites? Old URLs would likely no longer work (unless that is an acceptable side effect for the gain in better docs long term?).
Currently reported escalation path is Tutorials -> Docs -> IRC (to complain), will fixing the docs help those in IRC point people in the right direction and reduce these types of questions in IRC.