Discussion: New documentation content

Regardless of the environment of new documentation, whether WordPress, DocuWiki, GitHub, or vi into text files (kidding), the real focus should be on what we want to see in content, not so much how it's created or rendered.

Personally, here are my raw thoughts on the docs available for ISPConfig:

• The awesome series of Perfect installations is just the beginning of the road for the ISPConfig experience. They are tutorials, references, and the go-to RTFM for many forum posts. But they are not suitable for configuration or ongoing administration after the initial installation.
• The User Manual, also awesome for its purpose, tells us what buttons to press, but it doesn't tell us anything about what the software does, why, or how. Let's face it, it's also quite old and rather sparse on details. While RTFM might be a good response for many questions, this FM (and I say that with a respectful smile) may or may not be accurate in too many places given that it hasn't been updated in a few years.
  
• This leaves a huge gap which is now handled in these forums. There are questions about how users and jails work, subdomains and vhosts, DNS-related nuances, and every other feature that needs to be implemented by administrators. Some of the questions here are from people who don't understand the concepts. (I'll include myself in that category of "under-educated" wannabes.) But many are from ISP-employed administrators who simply don't know what is expected from ISPConfig: what values it sets in underlying applications, what folders it creates, permissions, restricted/insecure fields it does not set, and how exactly a secondary environment is instructed (currently via MySQL queries) to perform specific functions.

I see a LOT of questions in these forums about how things work, and a lot of instructions to just press whatever button we're told to fix it. But there is often little insightful information that can allow people to really use this software to its potential. "Anyone with interest can read the code." That's a dismissive engineer approach which discourages platform adoption. One should not have to know how to code at all in order to understand what the code does.

I could be wrong in a lot of that, but my perceptions are what they are, reinforced as I read more and more. To be clear, I also appreciate every note I see in a forum. People give their time to help others with no compensation. I do this in other communities - that's my FOSSy pay-forward/pay-back for the help I get in this world. What I'm seeing here is that the top contributors to these forums are spending a lot of time generously answering questions (with some visible frustration) when we should be able to Refer To Friendly Manuals.

So here is one aspect of what I'd like to see in new docs, ideally at https://docs.ispconfig.org/ based on notes in the other thread on this topic...

I think it would be good to have very well indexed content with a keyword index. The easier it is to search, the easier it is to point to an existing answer so that we can save time and move on to other topics. There should be many ways to get access to a topic. There should be many relevant See-Also references. Extensive indexing is helpful to facilitate the web surfing experience so that people can get all information available about a concept.

Contributions of links to related topics should be as welcome as any other on-page content. Links to other fundamental resources are important because we frequently see that people need more information about a topic before they're competent and confident to press the buttons as instructed in docs and forums.

I don't see a doc site for ISPConfig as being constructed from one complete page at a time. I think all content evolves because there is always some new relevant bit of information that can be added. If we look at the User Manual there are a lot of topics and I think it would help to create a page stub for a lot of those, and then fill in the stubs over time. Anyone who has something to contribute can add to these pages about how and why things work as they do, with links back to the manual for how to implement the details. I'm not suggesting a wiki-style free-for-all, but a code-like system where contributions are submitted in a process like MR, verified, then merged into the content.

These are examples of topics that can start as a stub and get filled-in over time. Please don't debate specific topics, these are just examples. Yes, topics like this can be covered in HowToForge but this is all about detail specific to its use with ISPC :

• DNS ALIAS, CNAME, or A record?
• Where should a subdomain be hosted?
• How does ISPC work with a jail, permissions, user IDs and other authorization mechanisms?
• What does ISPC do related to BIND9 and named resolution?
• What kind of directives should go in .vhost files?
• What do we do about .htaccess?
• How do we customize the login page and new site index.html?
• What are all of the areas touched by certbot/LE, and what is Not done from ISPC?
• What is monitored? What is not? How can we add a new log monitor?
• How to manage (custom?) folder structures.
• How are SSH/SFTP users managed?
• What are some backup/recovery strategies?
• What can we monitor in SMTP/POP3/IMAP/spam/AV and related services, and what else do we need to do outside of ISPC?

In all of this, I am not proposing publication of the User Manual. I am not trying to make ISPConfig documentation a substitute for the million other resources for system administration. I am not proposing "Hosting an ISP for Dummies". I'm suggesting we stub out topics that are relevant to ISPConfig environment management and fill in content that's not provided elsewhere. A ton of this information is already in forums - a lot of wisdom there can be conveyed briefly in topical pages so that people don't need to be told how to use a search engine and site:howtoforge....

Thanks for your time and suggestions.

P.S. : And I'm not suggesting that @till or any other developer take the lead on all of this. I would be happy to create stubs, contribute content, edit, format, and respond to commentary and contributions. I won't pretend competence to do this all on my own. I'm just saying I have no intention to dump this on the people who are already fully occupied with what they do here.

 

There are three important Likes on that post ...

I completely agree that by publishing components of the Manual, there is a conflict with its nominal courtesy/sustenance fee. But I did say that the public content was not intended to duplicate or conflict with that content. If the material is different then there is no conflict. However, here's a proposal to address that directly.

Make the docs available by subscription-only for $1/month = $12/year. All subscriptions start on jan-1 and end on dec-31. The value-add compared to the lower-price static doc is that it's constantly updated, and people get an opportunity to influence the evolution of the content. Compare this to the free, static, outdated Perfect docs and others. It should still be conveyed that this is still not a "for fee" service, but that the funds are intended to help support the production costs of team-supported FLOSS.

For an additional monetization option, consider the HowToForge model : Public static content with ads, AND private dynamic contant without ads - or maybe just with better ads that are hand-picked for the audience rather than Google ads based on personal preference. ( I would much rather see an ad related to technology than about Mortgages or Brad Pitt - and I have no idea why that crap is fed to me by Google anyway.)

Unreasonable complaints about 12$/€ per year are easily dismissed, as this software is designed to support commercial, revenue-generating businesses that themselves have subscription fees - which go into the pockets of an ISP and not to FLOSS.

I maintain (and have probably poorly explained) that the "how it works" documentation that I'm talking about is different from the "which buttons to press" material in the manual. In the rest of the world these concepts are not separated - everything about a topic is in one place. By monetizing the docs as described abovem, adapting it to the same model as the existing docs, this confusing distinction can be eliminated.

For yet another monetization option, offer a PDF download of the content that is specifically categorized and intended for a "User Guide". This is exactly what is available now, just sourced from a collaboration-friendly environment, which addresses the other problem @Th0m cited. This PDF can be produced at the end of each year. So any jackass that publishes it will still have outdated and incomplete content, which includes references for readers to the low-cost current content. Will other jackasses scrape and republish the doc site? Sure, but there are ways to catch and ban them.

 

Please forgive, but I must inject an observation : You guys don't seem to recognize that obscurity really hurts this project. The less information there is, the fewer people there are who know about it. Your efforts to entice a $5 token of gratitude can easily cost a lot more. (And note again, I don't disagree with the trivial cost for docs.) The one person you get who pays the token is outweighed by a lot of people who don't bother to look at the software because few people outside of this little circle know about it.

Remember when I asked about writing a blog about the new user experience? I was anticipating exactly the experience that I have had with this fine software. Every question results in significant lost time with searches in multiple sources. We pay for "free" FOSS with our time - and you pay for it with your generous time in processing so many questions here. I've lost weeks of productive revenue-generating time with this wonderful free software that has tidbits of how it works in a lot of different places. Your "just look around and find your own answers" approach, while unfortuntely typical in our industry, is not appropriate for a package this big. That kind of thinking applies to foo.lib, not to business software that has a ton of components. The software suffers because the worldview of the developers hasn't evolved to meet with the expectations of the intended audience. YOU might be content to spend your time hunting for details in forums, old blog posts, FAQs, and an old PDF. But when time equals money, modern businesses need to consider the actual Cost of freeware. A higher cost of time=money is discouraging. It becomes less costly to use a closed-source for-fee package. The FOSS model fails when freedom leads to chaos, and when developers go broke doing what they love. More balance is required.

We all know that Extensibility is now an industry requirement. A platform without an API is worthless. ISPConfig has an API but it doesn't have easily accessible information that tells people what the platform does. Yeah, we can plug into it after we spend weeks in these forums trying to figure out how it works. Obscurity is the opposite of Extensibility. Don't hide documentation, and don't use "we'll lose money" as an excuse for not producing documentation. The more people know the more they will embrace the platform.

In every review that I've read comparing ISPConfig to other packages, the common evaluation is that ISPConfig is difficult to understand and that support is tough to get - and while ISPConfig ranks high in all reviews on functionality, it's popularity remains low. This leads to questions about its longevity. I have seen this exact scenario play out in other companies. Do NOT get defensive and argue with the reality of these points. These are observations by many people, and if we all have the same perception then your counter-argument is irrelevant. It is a reality that ISPConfig doesn't get the usage and credit that it deserves because it is too obscure. I hate to see that happen. Everything that I talk about here with regard to blogs and docs is intended to help with that. You guys need to look beyond your own perspective and think about how the rest of the world sees this software. Ask yourself if it's possible that you might not be able to see this software anymore like others do. It's too easy for the rest of the world to see ISPConfig as it is and then continue to seek out alternatives. Let's fix that.

Or perhaps another way to look at this is that you view ISPConfig from an individual technical/engineering perspective, which is not appropriate for software intended to appeal to a broad commercial audience. Someone involved with this software needs to put on a Marketing hat, and think about what will get more people to use this awesome software. That's far outside the comfort zone for most gearheads like us.

-- Arguably useless commentary and advice from a Product Marketing Manager, Business Owner, Startup Mentor, Tech Evangelist, and Prolific Writer

 

I was hoping to focus threads on specific topics but such efforts are rarely successful. The other thread is about tooling. This one was intended to be about content. Another thread should have been about access, including price, scope of distrubution, etc.

Let's focus on content, with reference back to the OP for this thread.

I'm thinking a valuable asset for this software would be a lot of articles, each focused on a single topic. Being dynamic, the content in each page will get updated with verified wisdom from the forums, and whatever other detail people care to contribute. Think of this as always being a work in progress, like software, where issues are reported, processed, and closed. "Bugs" can include incomplete or inaccurate content, and requests for enhancements. So it starts with a lot of page stubs that have very little content, and each page getting filled in and updated as more information gets harvested from the forums and other sources. If someone believes a post in these forums has wisdom that should be included in the docs, they can hashtag it like #doc, or use some other unique defined marker that can be searched.

This does not conflict with the Manual, which is mostly a top-down description of UI features. It's a reference guide for "what is expected at this prompt", not "what do I do if I want to ..." or "what happens internally when I check that box" or "where do I go to find more information about this topic".

Can we all get on board with these basic concepts? Thanks.

 

This sounds like the current Tutorials section.
With the current system I see problems, and new system should aim to make it better:

• Tutorial can not be modified after publication (by the author). This parallels printed publication, but I find it is a problem when some error or incomplete instruction is discovered. Even printed books have second editions.
• Finding the Tutorial needed is not easy. I believe quite a lot of cases in the forum would be avoided if user had read the suitable tutorial.
• The tutorial page has nothing to clue the user to look at the Tags section to help find suitable tutorial.
• Old tutorial do not show publication date. New ones do. The old ones should be marked Published before <date> where date is when tutorias started having publish date.
• Tutorial should be marked "OBSOLETE" when it no longer is correct or is replaced by another tutorial

 

I'm not proposing "just" Tutorials. I've already provided examples of the kind of content that I am proposing, so let's expand the discussion.

Consider what we have here in this little microcosm of a thread : One well-respected person says information is difficult to find and another well-respected person says it's not. That's an obvious sign that there is some kind of problem that bears some inquiry, perhaps a reconsideration of perspective.

I noted reviews of ISPConfig that say the same thing, and the reviews are dismissed as biased for some nefarious purpose. I don't argue with the accurate reasoning, pay for play in the industry, etc. But I don't believe it's logical to dismiss comments with no inquiry into specifics.

I started my experience with this software with no information at all, suggested in my first post here that some documentation might be of use to others, and the suggestion was dismissed.

This forum is full of questions and very insightful answers. The volume of questions is blamed on people not doing enough searching.

All of this should provide a hint that developer perceptions here do not coincide with user perceptions.

Our own impressions of our software is irrelevant. As a developer, it doesn't matter if I think my documentation is adequate. If my clients can't use the software then I improve the docs until they can do so without help. The same applies to on-screen tips, error messages, and logs. User questions and public feedback provide valuable business intelligence, which should not be defensively dismissed. ("They're all wrong, it's their problem, they're lazy, my product is fine...")

You have here an opportunity address a long-term problem that others recognize even if you don't.
How does it hurt the platform to have more documentation that you personally don't think is necessary?
Can more information possibly be bad for this software or any other FOSS?
Will details about how things work, for people who want them, in any way hurt people who don't care about details?
Assume that more links and more references and more keywords and more articles will not be used by a category of people who choose not to read: Why should professionals who DO read suffer for the incompetence of others?
Wouldn't it be better to have documentation to refer people to, rather than to keep writing answers in the forum and hunting for links there?
Doesn't it seem logical that if people know how this software works that there will be more contributors?
And doesn't it seem reasonable that more contributors increases prospect/user confidence, increases the user base, and thus provides a larger base for prospective revenue by whatever means you are comfortable?

Unless there is actually something negative about having more documentation, is there an objection to just starting the process to see how it goes, and then re-evaluating later?

Thanks as always

 

actually, for this question, i'd say the answer is yes.
if the information is just plain wrong ( or perhaps written by someone who inadvertently, incorrectly configured their own system and whilst it may, perfunctorily, appear to work, does not work correctly and will certainly cause further problems), outdated, or contradictory.
it will cause frustration, disillusionment, and potentially bias people against that bit of software.

the tutorials on here, and some of the forums, cover a wide range of topics, and even searching on here for answers can return a lot of results, many of which, even after careful selection of keywords, are not relevant to the original query. perhaps, partly due to less experienced users creating threads asking the wrong questions, or not knowing what they should be asking.
if your end result is an ispconfig (and constituent components) centric resource of verifiable, accurate information, my suggestion would be a fully searchable knowledgebase style site, and where topics can be split into areas (eg dns, apache, nginx, mail, jailkit/chroot) and where articles are firstly only posted ( or posted privately to a select group, and then only made publicly available), when a number of users deemed knowledgeable/reliable enough on that subject matter have confirmed the contents of the article be correct.
that way it can be deemed as the reliable, preeminent source of configuration and trouble shooting information, with the forum being the place to ask questions when you can't find the issue/solution in the knowledgebase.

 

@nhybgtvfr - You've rephrased what I've been writing and my intent. It seems we're all on the same page with the high level view. We're not just talking about "information" or "tutorials" or any one kind of documentation. The hunger here is for current, verified, accurate, and compete sets of facts on specific topics to be easily accessible and useful - for those who dare to visit such a resource before posting in a forum. There are always challenges to accomplish these goals. There are solutions to each challenge. I would rather face those challenges with an existing KB, than not to have a KB and face the daily challenges that consume my time now.

 

If fixing tutorials is possible, I would like to get some correction to my e-mail setup tutorial at https://www.howtoforge.com/how-to-install-an-email-server-with-ispconfig-on-debian-10/
The chapter Open ports is missing info on how to test if port is open. I wrote that in comment for that tutorial, so the contents of that comment should be added to this chapter.

Also examples have newlines missing, like this:

Code:

root@posti:~# hostname posti
 root@posti:~# hostname -f posti.taleman.ovh
 root@posti:~#