Docs Category and Polling Devs
I was chatting with @slafleche about docs and realized that some of our missing ones are out of my depth to write, however I dont know the best way to pester developers for this information.
I'd like someone to double check documents for content and not just typos in the rough draft phase, or they will inevitably go up incomplete.
Simple questions like, are these all the parameters that are possible to use in advanced search? are things that are going to be very low on the priority list for a dev to help out with, but if the answer is "no" that still makes for a incomplete doc.
Stephane mentioned he'd like to documentation on all the modules available in vanilla. My only current guide for that is here: https://blog.vanillaforums.com/help/list-of-modules-for-your-themes/ but this list is incomplete now. I'm not dev enough to dive into the source code and find this info, but not documenting modules correctly will create confusion and mix up expectations for what a bit of code actually does. Clarity here is important, so I'm hesitant to just wing it, have no one actually read it, and then just wait for that doc to cause problems for a client down the line.
Carving out time from the devs is already a difficult task. I want to know what the best way to approach working in tandem on docs with the people who understand the code is. My thought is to create a staff forum category for docs, so I can slowly accumulate information in a public space and have people add to it. I'd also like to assign pull requests to someone to review with actual scrutiny.
I'm open to any input on this!
Comments
-
@laura, I really like idea of a category for docs, but I'd also recommend, when anyone gets answers that have template or code tricks to post it on the forum too, to help build the docs. As you know things get lost in Hipchat. It will be important for the poster to use descriptive titles too, so it makes it easier to identify and allow others to add important info about the topic.
Also It's kind of hard to randomly think of things to know -- so it will be important that when a quick answer uncovers a tip or trick with Vanilla, we have a quick place to post it, so the staff forum category is a great idea.
I know the devs are adding so much now, but I'm not searching for solutions like I used to. I never know about the new stuff unless I go searching to help solve a problem.
I am happy to help where I can (to read drafts or comment on code here), but ultimately the devs are the best checkers for docs as things get deprecated or they might offer a more optimal solution.
Maybe the "dev" on call for the week, could review the new docs proposed to be added. I'm not sure how many you add a week and maybe I'm wrong and it's too much work. However, by having a defined schedule with the devs, it might help speed up the addition of new content...
0 -
The support dev already has enough dealing with support for 2 weeks, it's not really reasonable to just add this to their workload.
I want a developers input for better chances of accuracy. I can also have Andrew or one of the CSMs read over my drafts, but its not quite the same in terms of knowledge of the current code.
0
