Discussion: New documentation content

Discussion in 'Developers' Forum' started by TonyG, Oct 4, 2020.

  1. TonyG

    TonyG Active Member

    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.
    Last edited: Oct 4, 2020
  2. Th0m

    Th0m ISPConfig Developer Staff Member ISPConfig Developer

    I think I have commented this before... but will comment it anyway.

    We are working on a new platform for the current manual, that can be accessed by HTF subscribers. The current manual is out of date because it is one big file that can not be edited easily. In the future, we will split it into separate files and we want to allow several people to propose changes, for example through merge requests in a separate GitLab project.

    I don't think it is a good idea to write more docs that are available to everyone, as the manual encourages people to pay a small amount of money to support ISPConfig and it's development. If we create even more docs, there is more to maintain and verify.

    Also, a lot of questions on the forum are already answered by the manual or even in tutorials on HowToForge. We also have faqforge.com, take a look at it (especially under the tag ISPConfig 3). Some people just don't search for a answer but ask it right away on the forums. Writing more docs would not fix this 'problem', as they won't read them anyway. But we do link to some posts on faqforge.com sometimes, for example https://www.faqforge.com/linux/cont...ange-in-pure-ftpd-on-denian-and-ubuntu-linux/

    I'm not sure if @till regularly adds topics about ISPConfig suggested by others to faqforge, but if so, you can propose a eventual new topic to him.

    That said, when we have figured out what we will do for the 'new' manual system, we could add some more information about software and best practices. But I think it's better to look into the separate topics when the manual is converted, so you can easily comment on separate sections.
    Croydon, till and ahrasis like this.
  3. TonyG

    TonyG Active Member

    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.
  4. TonyG

    TonyG Active Member

    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
  5. till

    till Super Moderator Staff Member ISPConfig Developer

    ISPConfig uses a different approach to split services than e.g. Plesk. That's intended and that irritates users that have seen Plesk only. It's the same as if you put a mac user in front of windows or a windows user in front of a Linux desktop. A mac user will probably tell you that Linux and Windows are both completely unusable. Users that love ISPConfig do it because it does not work like Plesk and we developed it work the way it works as we see it as a better and more logical approach to group functions and we will not become a Plesk clone just to please some Plesk users.

    That's actually not the case. I get frequently emails from users which even state that our free support in the forum is better than the paid support they receive from Plesk and CPanel.

    ISPConfig is quite popular and probably one of the most used open-source hosting control panels worldwide with an installation base of many hundred thousand servers and there are quite a few large providers that run internally thousands of ISPConfig systems in their networks. That it's not used even more (and therefore not more visible to some people) is caused by large server providers, they expect the control panel vendor to pay them a kickback for each installation, which we can't do since ISPConfig is free, so we can't give them let's say 5 usd/month for each ispconfig installation that they sell to their customers. That's why they prefer to promote CPanel & co instead of a free panel.

    That's completely wrong, if you compare various panels, then you find out that ISPConfig is one of the panels with the most active longtime development, development never stalled or was abandoned, as ISPConfig is backed by a company and active developer base for more than 15 years now.

    One can always find someone who did not hear of a specific software yet, and then he claims that this software can't be widely used because he did not know it himself before.

    Nontheless, I agree that there is a lot of room for improvements in the documentation and we can do that e.g. on docs.ispconfig.org. The base docs should not be made much more detailed as they are now as most users, unlike you, search for a solution for a problem and not an in-depth explanation of how a specific technology works. Most users find even the copy&paste perfect server tutorials gpoing to much in depth, they want to use just one of the auto-installers and don't care about anything on their server as lon as they have a login field in the browser at the end where they can log in and click on new website. So adding in-depth articles about various topics of a hosting system are a good idea, but they are not a replacement for a manual that comes right to the point. And sure, we can consider making the manual available for free, but this would mean to charge users for something else, and donations are not an option as they simply don't work, and selling support plans is not an option too as this would mean that the support time is paid and no money is left for the actual ISPConfig development. So only an ebook, as it's now, or a subscription that does not include any additional 'per subscriber' work time is an option.
    TonyG likes this.
  6. TonyG

    TonyG Active Member

    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.
  7. Taleman

    Taleman Well-Known Member HowtoForge Supporter

    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
  8. Th0m

    Th0m ISPConfig Developer Staff Member ISPConfig Developer

    This is already possible, @till can make it available in your account on request.
    This is something we discussed recently, but it is a lot of work to go through all tutorials, so no solution there yet.
  9. till

    till Super Moderator Staff Member ISPConfig Developer

    That's intended and must be like that after some authors started to sell links to seo agencies and put these links into the tutorials. But there is always the possibility to make new releases of a guide, just contact me.

    Finding tutorials is quite easy in my opinion, simply use the search function and type in what you are looking for. Or narrow it down using the tags page. The problem is that users do not even start to search for a tutorial, and that#s what you can't change.

    That#s already the case, old tutorials that have a newer version show a big info bar at the top that there is a newer version available.
  10. TonyG

    TonyG Active Member

    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
  11. till

    till Super Moderator Staff Member ISPConfig Developer

    I nowhere said to not write more or better docs. I just said that most users tend to not willing to look for a solution themself instead of asking, so no matter how many docs you have, this won't change, even if the solution is the first match for their query on Google and co.

    Not at all, we were actually at that point already: https://www.howtoforge.com/community/threads/discussion-new-documentation-environment.85149/

    @TonyG: I'll prepare a login for the ispconfig docs website for you next week, so you can get started.
    TonyG likes this.
  12. nhybgtvfr

    nhybgtvfr Well-Known Member HowtoForge Supporter

    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.
    TonyG, exynenem and Th0m like this.
  13. TonyG

    TonyG Active Member

    @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.
  14. Taleman

    Taleman Well-Known Member HowtoForge Supporter

    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:
    root@posti:~# hostname posti
     root@posti:~# hostname -f posti.taleman.ovh

Share This Page