- This topic has 9 replies, 5 voices, and was last updated 5 years, 5 months ago by
.
-
Posts
-
-
Appreciate the docs needed a workover in the lead up to 1.0, but I’m finding it really frustrating the there’s no *documentation* index; instead we get a mishmash of tutorial and doc code. I want to cut to the chase, and just read the API docs, but I can’t. It’s all mixed in now, and search is really inconsistent.
This page:
https://piklist.com/learn/doc/
redirects back to the top of the ‘learn’ section – surely it should be an index for the core docs?
I stumbling into a page like this:
with a title like:
Settings Section [File Structure]And think, ok, it looks like there are a number of [File Structure] pages. put ‘file structure’ into search, and… no results.
-
@hughc– Sorry for the frustration. The documentation is a work in progress. Since Piklist does so much, the users we surveyed seemed to like this format.
-
Hey @hughc!
There’s always the tension between the newcomer looking to learn and the experienced user trying to look up a quick reference. In the future, I think it would be great to use something like PHP Doc to build out an API based on our DocBlocks. The good news is that if you’re using something like Atom, PhpStorm, or another editor that has PHP parsing, you can pretty easily access the API that way. It’s obviously not ideal, but you could also easily use PHP Doc to make yourself a local API. We’ve really tried to make sure that the Piklist code is well internally documented to the DocBlock standard.
Hope this helps!
-
yes agreed.
It took my about 5 minutes to find some ‘basic’ file settings again:This was not intuïtief at all.
Also the search for ‘file structure’ did not give any links back.
Hope this gets a bit better structured in the future.
But as always, keep up the good work
Still love Piklist -
-
Sorry all– we’re still in the process of organizing it. I just added a list of the “types” of documentation to the sidebar. Should make it a little easier to find what you need >
-
-
Appreciate it, @Steve!
And if you have a list of holes in the docs that you want to see filled, shoot me an email and let me know if I can contribute. Piklist enabled me to take on a project I didn’t think I was capable of, and has been the catalyst for so much growth in my own dev skills. Now it’s the first plugin I install on any project. It would be an honor to give back!
-
This is a big step in the right direction @sbruner ! Helps a lot when trying to drill down to a particular feature.
-
-
- The topic ‘new docs problems’ is closed to new replies.