If I'm understanding christian correctly, I think his point is especially important in the case of 3.0 and the UI changes. While I probably dislike the "cookbook" approach less than christian (sometimes you need a recipe to get you started; experimentation can come later, as how things work gets clearer--always moving from the known the the unknown), I completely agree that a global understanding of how Zentyal works and why it works the way it does is important and desirable,
This broad, global understanding helps bridge the changes across major revisions. Signifincant changes to the UI can be sorted out based on a general understanding of how Zentyal works, even if that understanding is incomplete or fairly simple.
I think 3.0 is a case in point, where there are some substantial changes to the UI but less substantial changes to the underlying operation. If the UI changes confused me at first (and they did sometimes), I could fall back on my (simple) sense of how Zentyal works and figure it out.
So to me, as I've said before I think, the "best" approach to the documentation is task-oriented. "Want to do task A? Zentyal features X, Y, and Z are the tools you need. They accomplish the task in this way, and they interact in this way. Here are some common configurations for these common use case scenarios (these are only suggestions to get you started; specific help is available through Zentyal professional and community support)."
One of the challenges is to think like a newbie thinks, and then construct documentation accordingly. In other words, don't expect people to leave the documentation to understand/learn what something like "Kerberos" is in broad terms--the name itself carries zero helpful information beyond being a search term. Don’t write documentation at all following the traditional "buck up and learn Linux" approach, which is always a questionable attitude (IMHO) when it comes to small business IT. Whether small businesses outsource IT, or try to keep IT in house as much as possible, or use some combination of those (especially with some services easily moved to cloud providers), the real people doing the work (even just as users) have to do many things within their business context and rarely become expert at any one thing--at least in the time they have on the payroll. The practical difficulty from a documentation writer's point of view is getting the layers rights--bite-sized, logical, and working from the known to the unknown, the sweet spot where all real learning takes places.
Just my own opinion, as always.
Professional support
Certified training
Become a partner
Topic: Restructuring Zentyal Community Documentation Repositories (Read 352 times)