I think it’s not always easy to find the Kirby documentaton you want.
Google is not awesome for Kirby docs
Google often don’t give me a great result when I search for Kirby documentation. Kirby is a CMS with a small user base. Instead of Kirby CMS, the pink blob is showing up in the search result.
When @bastianallgeier has the time he update the docs. Can we help him with that? If that page was editable from the front end we could submit suggestions to documentation changes. Then it’s approved, denied or edited and then submitted.
That would be easy for Bastian and for the editor person that would like to help.
Github
Here we can find undocumented functions and how to use them. As soon as they are released I think they should be added to the docs as well.
Forum
Here we can ask questions how to solve things, like an extension of the documentation. Some of the solutions should be copied to the documentation page of that function. If the solutions are long, add a section of external links for reading more.
Changelog
Maybe I’ve learnt the most by reading all the changelog. When adding documentation to the changelog, add the same information to the docs.
In conclusion
Make us edit the documentation directly on the page which could be accepted, denied or edited.
Copy all valuble documentation to the docs from Github, Forum and Changelog.
It does’nt matter how good a function is if we do not know it exists, or what to do with it.
Did you know that you can already edit the Docs on Github? https://github.com/getkirby/getkirby.com/ You can even use Github’s Interface to submit changes instantly.
[quote=“jenstornell, post:1, topic:1447”]
###In conclusion
Make us edit the documentation directly on the page which could be accepted, denied or edited.[/quote]
I did not know of edit by the Github interface, nice!
Then I have another suggestion that comes close to my suggestion.
Edit this page on Github
Add an “Edit this page on Github” button on every documentation page with a link directly to the page on Github. I think many more would like to help that way, and it’s easier not needing to find the page in two structures.
Nice preview editor
On github the Kirby documentation with markdown looks like a mess (plane text), but I found a very nice online markdown editor to preview what we write.
And if it still feels too complicated for some to use Github at all, I already offered to everyone in the forum to help: Just send me the additions and/or changes to the docs that you think should go in there and I will take care of creating the right pull request for it.
I think everyone agrees with what you said. But writing docs also takes up quite some time which is very limited for a single developer like Bastian. Of course a release could take some weeks/months longer till all the docs are finished. But we prob don’t want that either. That said a complete documentation is very crucial and vital, no doubt. I would love to see the growing Kirby community to step up and help with this even more
Also when I search on Google I always use “getkirby” instead of “kirby”. Much better results that way! You won’t avoid seeing the odd pink Nintendo character though
Speaking of the forum, a lot of potential documentation was lost when @bastianallgeier pulled v1 of the forum offline. I understand that there could be confusion between v1 and v2 code, but how difficult would it be to put the v1 forum as an archive up on Github?
You can download the old forum contents from Github if you want. It doesn’t make sense to have an obsolete forum with old stuff online anymore, in fact that would probably raise more questions than it solves, especially for newbies.
Often when I’m searching for kirby-related things, I still get google results that point me to the old forum. Obviously when I follow the link it’s not there anymore… I fear that newbies will get discouraged by this.
But would the better option be that they get the google results which lead them to the old forum with outdated information, they try to implement it and fail?
@samnabi: I guess that will be the case for a little while longer but eventually these search results will disappear from google search and be replaced with the new results from the new forum. That would not happen if the old forum was still in place.
I get happy when I find what I’m looking, but then not so happy when I found out it’s deleted. I think @samnabi has a point, but the solution might not be to restore the old forum.
The solution would probably be for someone with time to go through all the threads and look for solutions to potential problems. Many solutions for Kirby 1 will probably still work for Kirby 2 or with some minor edits.
The real problem might find the guy with the ambition and time to get the good parts from the old forum and put it in the docs.
My main concern is that the old forum was more than just snippets of code – it chronicles the early discussions of the Kirby community, and that’s valuable in itself. There’s no reason the whole thing shouldn’t be accessible somehow.
Each page of the old forum could have a warning that the code may be obsolete. But hiding it deep in a Github repo? We’ve essentially erased part of the Kirby community’s history.
Trying to find the right place in the Github repo… I went back to this commit which was before Bastian posted the announcement of the new forum. But I can’t find the old forum content? The forum submodule seems to link back to this new one.
If it’s possible to have the same URLs, that would be great. Cool URLs don’t change and all that. But it could be accessed somewhere within the docs under “Kirby v1 forum (archived)”
The first point 1 agree fully,
but I want to search in the old forum (with the NEW name of the first point), e.g. if I don’t know the answer to find answers from v1 is better than to find no answer, I think.
I agree with @HeinerEF! I just figured out a way for us to use Google in a good way.
In the title tag, add something like this:
OLD: Whatever the thread is about - Kirby 1 Archives
That way we can easily spot the old forum right on the Google search page. 5 characters in the beginning of the title to show us that this might not work, but maybe.
“Kirby 1” at the end for searches related to the old forum.
